</div>

## Migration reference

| v0 方法                    | v1 方法               |
| ---------------------------- | ----------------------- |
| `sdk.adminLedger.createUser` | `sdk.用户.create`       |
| `sdk.userLedger.grantRights` | `sdk.用户.rights.grant` |

用户 namespace migration

## See also

* `钱包-sdk-config` - SDK 配置
* `用户 management` - 用户 management overview

{/* COPIED_START source="splice-钱包-kernel:docs/钱包-集成-guide/src/钱包-sdk-v1-migration-guide/amulet.rst" hash="3ccdd060" */}

# Amulet Namespace

The amulet namespace is used for Canton coin specific operations.

## Availability and extensibility

The amulet namespace is an extended namespace that requires 配置. 你可以 initialize it either during SDK creation or later using the `extend()` 方法.

**Option 1: Initialize during SDK creation**

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const sdk = await SDK.create({
  auth: authConfig,
  ledgerClientUrl: 'http://localhost:2975',
  amulet: {
      validatorUrl: 'http://localhost:2000/api/validator',
      scanApiUrl: 'http://localhost:2000/api/scan',
      auth: amuletAuthConfig,
      registryUrl: 'http://localhost:2000/api/registry'
  }
})

// amulet namespace is now available
await sdk.amulet.traffic.status()

// Create basic SDK first
const basicSDK = await SDK.create({
    auth: authConfig,
    ledgerClientUrl: 'http://localhost:2975'
})

// Extend with amulet namespace when needed
const extendedSDK = await basicSDK.extend({
    amulet: {
        validatorUrl: 'http://localhost:2000/api/validator',
        scanApiUrl: 'http://localhost:2000/api/scan',
        auth: amuletAuthConfig,
        registryUrl: 'http://localhost:2000/api/registry'
    }
})

// Now amulet namespace is available
await extendedSDK.amulet.traffic.status()

type AmuletConfig = {
    auth: TokenProviderConfig
    validatorUrl: string | URL
    scanApiUrl: string | URL
    registryUrl: URL
}

***

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const createPreapprovalCommand = await sdk.amulet.preapproval.command.create({
   parties: {
      receiver: partyId,
   },
})

await sdk.ledger
      .prepare({
         partyId: partyId,
         commands: createPreapprovalCommand,
      })
      .sign(privateKey)
      .execute({
         partyId: partyId,
      })

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { Holding, PrettyContract } from '@canton-network/core-tx-parser' import { localNetStaticConfig, SDK } from '@canton-network/wallet-sdk' import { pino } from 'pino' import { TOKEN_NAMESPACE_CONFIG, TOKEN_PROVIDER_CONFIG_DEFAULT, AMULET_NAMESPACE_CONFIG, } from './utils/index.js'

const logger = pino({ name: ‘v1-05-preapproval’, level: ‘info’ })

const sdk = await SDK.create({ auth: TOKEN_PROVIDER_CONFIG_DEFAULT, ledgerClientUrl: localNetStaticConfig.LOCALNET_APP_USER_LEDGER_URL, token: TOKEN_NAMESPACE_CONFIG, amulet: AMULET_NAMESPACE_CONFIG, })

await sdk.amulet.tapInternal(‘1000’)

const aliceKeys = sdk.keys.generate()

const alice = await sdk.party.external .create(aliceKeys.publicKey, { partyHint: ‘v1-05-alice’, }) .sign(aliceKeys.privateKey) .execute()

const [amuletTapCommand, amuletTapDisclosedContracts] = await sdk.amulet.tap( alice.partyId, ‘10000’ )

await sdk.ledger .prepare({ partyId: alice.partyId, commands: amuletTapCommand, disclosedContracts: amuletTapDisclosedContracts, }) .sign(aliceKeys.privateKey) .execute({ partyId: alice.partyId })

const bobKeys = sdk.keys.generate()

const bob = await sdk.party.external .create(bobKeys.publicKey, { partyHint: ‘v1-05-bob’, }) .sign(bobKeys.privateKey) .execute()

// --- TEST CREATE COMMAND

const createPreapprovalCommand = await sdk.amulet.preapproval.command.create({ parties: { receiver: bob.partyId, }, })

logger.info( { createPreapprovalCommand }, ‘Successfully created a preapproval command’ )

await sdk.ledger .prepare({ partyId: bob.partyId, commands: createPreapprovalCommand, }) .sign(bobKeys.privateKey) .execute({ partyId: bob.partyId, })

logger.info(‘Successfully registered the preapproval.’)

// --- TEST FETCH

const start = performance.now() const fetchOnceStatus = await sdk.amulet.preapproval.fetchQuick(bob.partyId) const end = performance.now()

const duration = end - start if (duration < 1000) { logger.info( Success! The operation was fast (${duration.toFixed(2)} ms) and fetchOnce status is ${fetchOnceStatus}. ) } else { logger.warn( Warning: Operation took longer than 1 second (${(duration / 1000).toFixed(2)} s). ) }

logger.info(‘Fetching for preapproval status with retry’)

const fetchedPreapprovalStatus = await sdk.amulet.preapproval.fetchStatus( bob.partyId )

logger.info({ fetchedPreapprovalStatus }, ‘Fetched preapproval status’)

const sentValue = 2000

const [transferCommand, transferDisclosedContracts] = await sdk.token.transfer.create({ sender: alice.partyId, recipient: bob.partyId, amount: sentValue.toString(), instrumentId: ‘Amulet’, registryUrl: localNetStaticConfig.LOCALNET_REGISTRY_API_URL, })

await sdk.ledger .prepare({ partyId: alice.partyId, commands: transferCommand, disclosedContracts: transferDisclosedContracts, }) .sign(aliceKeys.privateKey) .execute({ partyId: alice.partyId })

logger.info({ sentValue }, ‘Executed transfer from Alice to Bob with value:’)

const aliceUtxos = await sdk.token.utxos.list({ partyId: alice.partyId }) const bobUtxos = await sdk.token.utxos.list({ partyId: bob.partyId })

const partyAmuletValue = (utxos: PrettyContract[]) => utxos.reduce( (acc, utxo) => acc + parseFloat(utxo.interfaceViewValue.amount), 0 ) const aliceAmuletValue = partyAmuletValue(aliceUtxos) const bobAmuletValue = partyAmuletValue(bobUtxos)

if (aliceAmuletValue !== 8000 || bobAmuletValue !== 2000) throw Error( Wrong end results for utxos: ${JSON.stringify({ aliceAmuletValue, bobAmuletValue })} )

logger.info({ aliceAmuletValue, bobAmuletValue }, ‘Result:’)

// --- TEST RENEW COMMAND

logger.info(‘Renewing preapproval…’)

const start2 = performance.now() const fetchOnceStatusWithPreapproval = await sdk.amulet.preapproval.fetchQuick( bob.partyId ) const end2 = performance.now()

const duration2 = end2 - start2 if (duration < 1000) { logger.info( Success! The operation was fast (${duration2.toFixed(2)} ms) and fetchOnce status is ${fetchOnceStatusWithPreapproval}. ) } else { logger.warn( Warning: Operation took longer than 1 second (${duration2.toFixed(2)} s). ) }

const newExpiresAt = new Date(fetchedPreapprovalStatus!.expiresAt) newExpiresAt.setDate(newExpiresAt.getDate() + 2)

await sdk.amulet.preapproval.renew({ parties: { receiver: bob.partyId, }, expiresAt: newExpiresAt, })

const fetchedStatusAfterRenew = await sdk.amulet.preapproval.fetchStatus( bob.partyId, { oldCid: fetchedPreapprovalStatus!.contractId, } )

const before = fetchedPreapprovalStatus!.expiresAt const after = fetchedStatusAfterRenew!.expiresAt

if (!(after.getTime() > before.getTime())) { throw new Error( Expected expiresAt to increase after renewal. before=${fetchedPreapprovalStatus!.expiresAt.toISOString()} after=${fetchedStatusAfterRenew!.expiresAt.toISOString()} ) }

logger.info( { before: before.toISOString(), after: after.toISOString(), extendedSeconds: Math.round( (after.getTime() - before.getTime()) / 1000 ), }, ‘TransferPreapproval expiry extended, managed to renew preapproval’ )

// --- TEST CANCEL COMMAND logger.info(‘Testing out cancel command’)

if (!fetchedStatusAfterRenew?.templateId) { throw new Error(‘No preapproval found - fetchedPreapprovalStatus is null’) } const [cancelPreapprovalCommand, cancelDisclosedContracts] = await sdk.amulet.preapproval.command.cancel({ parties: { receiver: bob.partyId, }, })

if (!cancelPreapprovalCommand) { throw Error( ‘Cancel preapproval command is null even though one has been created before’ ) }

await sdk.ledger .prepare({ partyId: bob.partyId, commands: cancelPreapprovalCommand, disclosedContracts: cancelDisclosedContracts, }) .sign(bobKeys.privateKey) .execute({ partyId: bob.partyId, })

logger.info(‘Submitted cancel command; now polling’) const cancelled = await sdk.amulet.preapproval.fetchStatus(bob.partyId, { cancelled: true, })

const preapprovalACS = await sdk.ledger.acsReader.readJsContracts({ parties: [bob.partyId], filterByParty: true, })

const renewedPreapprovalStillActive = preapprovalACS.some( (contract) => contract.contractId === fetchedStatusAfterRenew?.contractId )

if (cancelled === null && !renewedPreapprovalStillActive) { logger.info(Successfully cancelled) }

</div>

**Buy Member 流量**

<div className="before-after">
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const buyMemberTrafficCommand =
   await sdk.tokenStandard.buyMemberTraffic(
      senderPartyId,
      amount,
      participantId,
      inputUtxosOptional
   )

---

const [buyTrafficCommand, buyTrafficDisclosedContracts] =
   await sdk.amulet.traffic.buy({
      buyer,
      ccAmount,
      inputUtxos: [],
   })

await sdk.amulet.traffic.status()

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} import pino from 'pino' import { localNetStaticConfig, SDK } from '@canton-network/wallet-sdk' import { TOKEN_NAMESPACE_CONFIG, TOKEN_PROVIDER_CONFIG_DEFAULT, AMULET_NAMESPACE_CONFIG, } from './utils/index.js'

const logger = pino({ name: ‘v1-06-merge-utxos’, level: ‘info’ })

const sdk = await SDK.create({ auth: TOKEN_PROVIDER_CONFIG_DEFAULT, ledgerClientUrl: localNetStaticConfig.LOCALNET_APP_USER_LEDGER_URL, token: TOKEN_NAMESPACE_CONFIG, amulet: AMULET_NAMESPACE_CONFIG, }) const aliceKeys = sdk.keys.generate()

const alice = await sdk.party.external .create(aliceKeys.publicKey, { partyHint: ‘v1-07-alice’, }) .sign(aliceKeys.privateKey) .execute()

const bobKeys = sdk.keys.generate()

const bob = await sdk.party.external .create(bobKeys.publicKey, { partyHint: ‘v1-07-bob’, }) .sign(bobKeys.privateKey) .execute()

const createPreapprovalCommand = await sdk.amulet.preapproval.command.create({ parties: { receiver: bob.partyId, }, })

await sdk.ledger .prepare({ partyId: bob.partyId, commands: createPreapprovalCommand, }) .sign(bobKeys.privateKey) .execute({ partyId: bob.partyId, })

// Mint holdings for alice

const [amuletTapCommand, amuletTapDisclosedContracts] = await sdk.amulet.tap( alice.partyId, ‘2000000’ )

await sdk.ledger .prepare({ partyId: alice.partyId, commands: amuletTapCommand, disclosedContracts: amuletTapDisclosedContracts, }) .sign(aliceKeys.privateKey) .execute({ partyId: alice.partyId })

logger.info(Tapped holdings for alice)

const trafficStatusBeforePurchase = await sdk.amulet.traffic.status()

logger.info( Traffic status before purchase: ${JSON.stringify(trafficStatusBeforePurchase)} )

const ccAmount = 200000

const [buyTrafficCommand, buyTrafficDisclosedContracts] = await sdk.amulet.traffic.buy({ buyer: alice.partyId, ccAmount, inputUtxos: [], })

await sdk.ledger .prepare({ partyId: alice.partyId, commands: buyTrafficCommand, disclosedContracts: buyTrafficDisclosedContracts, }) .sign(aliceKeys.privateKey) .execute({ partyId: alice.partyId })

logger.info(buy member traffic for sender (${alice.partyId}) party completed)

const utxos = await sdk.token.utxos.list({ partyId: alice.partyId }) logger.info(utxos, ‘alice utxos’)

const sentValue = 2000

const [transferCommand, transferDisclosedContracts] = await sdk.token.transfer.create({ sender: alice.partyId, recipient: bob.partyId, amount: sentValue.toString(), instrumentId: ‘Amulet’, registryUrl: localNetStaticConfig.LOCALNET_REGISTRY_API_URL, })

await sdk.ledger .prepare({ partyId: alice.partyId, commands: transferCommand, disclosedContracts: transferDisclosedContracts, }) .sign(aliceKeys.privateKey) .execute({ partyId: alice.partyId })

//TODO: This does not work when we run multiple code snippets parallel

// await new Promise((resolve) => setTimeout(resolve, 61_000))

// const trafficStatusAfterPurchaseAndSomeTime = await amulet.traffic.status()

// const difference = // trafficStatusAfterPurchaseAndSomeTime.traffic_status.target // .total_purchased - // trafficStatusBeforePurchase.traffic_status.target.total_purchased

// if (difference === ccAmount) { // logger.info( // { // trafficStatusBeforePurchase, // trafficStatusAfterPurchaseAndSomeTime, // }, // ‘MemberTraffic status. Traffic purchased successfully’ // ) // } else { // logger.error( // { // trafficStatusBeforePurchase, // trafficStatusAfterPurchaseAndSomeTime, // }, // ‘MemberTraffic status.’ // ) // throw new Error( // Member traffic difference is ${difference}, expected ${ccAmount} // ) // }

</div>

**Tap**

The is useful for 测试 against LocalNet or Devnet.

<div className="before-after">
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
await sdk.tokenStandard.createTap(partyId,
       amount,
       {
       instrumentId,
       instrumentAdmin
       })

---

await sdk.amuet.tap(partyId, amount)

import { localNetStaticConfig, SDK } from '@canton-network/wallet-sdk'

export default async function () {
    const sdk = await SDK.create({
        auth: global.TOKEN_PROVIDER_CONFIG_DEFAULT,
        ledgerClientUrl: localNetStaticConfig.LOCALNET_APP_USER_LEDGER_URL,
        amulet: global.AMULET_NAMESPACE_CONFIG,
    })

    const partyId = EXISTING_PARTY_1
    const privateKey = EXISTING_PARTY_1_KEYS.privateKey

    const [commands, disclosedContracts] = await sdk.amulet.tap(partyId, '200')

    // ledger namespace is immediately available
    await sdk.ledger
        .prepare({ partyId, commands, disclosedContracts })
        .sign(privateKey)
        .execute({ partyId })
}

await sdk.ledger
      .prepare({
         partyId: partyId,
         commands: [...],
      })
      .sign(privateKey)
      .execute({
         partyId: partyId,
      })

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { localNetStaticConfig, SDK, signTransactionHash, } from '@canton-network/wallet-sdk' import { pino } from 'pino' import { v4 } from 'uuid' import { TOKEN_NAMESPACE_CONFIG, TOKEN_PROVIDER_CONFIG_DEFAULT, AMULET_NAMESPACE_CONFIG, } from './utils/index.js'

const logger = pino({ name: ‘v1-01-ping-localnet’, level: ‘info’ })

const sdk = await SDK.create({ auth: TOKEN_PROVIDER_CONFIG_DEFAULT, ledgerClientUrl: localNetStaticConfig.LOCALNET_APP_USER_LEDGER_URL, token: TOKEN_NAMESPACE_CONFIG, amulet: AMULET_NAMESPACE_CONFIG, })

const senderKeys = sdk.keys.generate()

const sender = await sdk.party.external .create(senderKeys.publicKey, { partyHint: ‘v1-01-alice’, }) .sign(senderKeys.privateKey) .execute()

const senderFingerprint = await sdk.keys.fingerprint(senderKeys.publicKey)

logger.info({ sender, senderFingerprint }, ‘Sender party representation:’)

if (sender.publicKeyFingerprint !== senderFingerprint) throw Error(‘Inconsistent fingerprints’)

const receiverKeys = sdk.keys.generate()

const receiverPartyCreation = sdk.party.external.create( receiverKeys.publicKey, { partyHint: ‘v1-01-bob’, } )

const unsignedReceiver = await receiverPartyCreation.topology()

// external signing simulation const receiverPartySignature = signTransactionHash( unsignedReceiver.multiHash, receiverKeys.privateKey )

const signedReceiverParty = await receiverPartyCreation.execute( receiverPartySignature )

logger.info({ signedReceiverParty }, ‘Receiver party representation:’)

const pingCommand = [ { CreateCommand: { templateId: ‘#canton-builtin-admin-workflow-ping:Canton.Internal.Ping:Ping’, createArguments: { id: v4(), initiator: sender.partyId, responder: sender.partyId, }, }, }, ]

logger.info({ pingCommand }, ‘Ping command to be submitted:’)

await sdk.ledger .prepare({ partyId: sender.partyId, commands: pingCommand, disclosedContracts: [], }) .sign(senderKeys.privateKey) .execute({ partyId: sender.partyId })

logger.info(‘Ping command submitted with online signing’)

/* offline signing example */

const preparedPingCommand = sdk.ledger.prepare({ partyId: sender.partyId, commands: pingCommand, disclosedContracts: [], })

const { response: preparedPingCommandResponse } = await preparedPingCommand.toJSON()

logger.info({ preparedPingCommand }, ‘Prepared ping command:’)

/* Note: The following code uses the @canton-network/core-signing-lib as the ‘custodian’ of the private key to sign the prepared transaction hash, but in a real scenario, the signing could be done using any compatible signing mechanism, such as a hardware wallet or an external signing service. */ const signature = signTransactionHash( preparedPingCommandResponse.preparedTransactionHash, senderKeys.privateKey )

const signed = sdk.ledger.fromSignature(preparedPingCommandResponse, signature)

await sdk.ledger.execute(signed, { partyId: sender.partyId })

logger.info(‘Ping command submitted with offline signing’)

const [amuletTapCommand, amuletTapDisclosedContracts] = await sdk.amulet.tap( sender.partyId, ‘10000’ )

const result = await sdk.ledger .prepare({ partyId: sender.partyId, commands: amuletTapCommand, disclosedContracts: amuletTapDisclosedContracts, }) .sign(senderKeys.privateKey) .execute({ partyId: sender.partyId })

const senderUtxos = await sdk.token.utxos.list({ partyId: sender.partyId })

const tapTransaction = await sdk.token.transactionsById({ updateId: result.updateId, partyId: sender.partyId, })

const mintEvent = tapTransaction.events.find( (tokenStandardEvent) => tokenStandardEvent.label.type === ‘Mint’ && tokenStandardEvent.unlockedHoldingsChange.creates.find( (h) => h.amount === ‘10000.0000000000’ ) )

if (mintEvent) { logger.info(‘Found token standard event with type Mint’) } else { throw new Error(Couldn't find tap transaction by updateId) } const senderAmuletUtxos = senderUtxos.filter((utxo) => { return ( utxo.interfaceViewValue.amount === ‘10000.0000000000’ && utxo.interfaceViewValue.instrumentId.id === ‘Amulet’ ) })

if (senderAmuletUtxos.length === 0) { throw new Error(‘No UTXOs found for Sender’) }

logger.info(‘Tap command for Amulet for Sender submitted and UTXO received’)

</div>

**Active 合约 设置 (ACS) queries**

<div className="before-after">
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const contracts = await sdk.userLedger.activeContracts({
   offset,
   templateIds: [...],
   parties: [],
   filterByParty: true
})

const contractId = LedgerController.getActiveContractCid(contracts?.[0]?.contractEntry!)

---

const contracts = await sdk.ledger.acs.read({
   parties: [...],
   templateIds: [...],
   filterByParty: true
})

const contractId = contracts[0].contractId

***

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
//automatically checks if uploaded and skips if present
await sdk.ledger.dar.upload(darBytes, packageId)

const sdk = await SDK.create({
    auth: authConfig,
    ledgerClientUrl: 'http://localhost:2975',
    asset: {
        auth: assetAuthConfig,
        registries: [new URL('http://localhost:2000/api/registry')]
    }
})

// asset namespace is now available
const assetList = sdk.asset.list

// Create basic SDK first
const basicSDK = await SDK.create({
    auth: authConfig,
    ledgerClientUrl: 'http://localhost:2975'
})

// Extend with asset namespace when needed
const extendedSDK = await basicSDK.extend({
    asset: {
        auth: assetAuthConfig,
        registries: [new URL('http://localhost:2000/api/registry')]
    }
})

// Now asset namespace is available
const assetList = extendedSDK.asset.list

type AssetConfig = {
    auth: TokenProviderConfig
    registries: URL[]
}

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} import { JSContractEntry } from '@canton-network/core-ledger-client' import { TokenProviderConfig, localNetStaticConfig, } from '@canton-network/wallet-sdk' import { TokenConfig, AmuletConfig, AssetConfig, } from '@canton-network/wallet-sdk'

export function getActiveContractCid(entry: JSContractEntry) { if (‘JsActiveContract’ in entry) { return entry.JsActiveContract.createdEvent.contractId } }

export const TOKEN_PROVIDER_CONFIG_DEFAULT: TokenProviderConfig = { method: ‘self_signed’, issuer: ‘unsafe-auth’, credentials: { clientId: localNetStaticConfig.LOCALNET_USER_ID, clientSecret: ‘unsafe’, audience: ‘https://canton.network.global’, scope: ”, }, } export const TOKEN_NAMESPACE_CONFIG: TokenConfig = { validatorUrl: localNetStaticConfig.LOCALNET_APP_VALIDATOR_URL, registries: [localNetStaticConfig.LOCALNET_REGISTRY_API_URL], auth: TOKEN_PROVIDER_CONFIG_DEFAULT, }

export const AMULET_NAMESPACE_CONFIG: AmuletConfig = { validatorUrl: localNetStaticConfig.LOCALNET_APP_VALIDATOR_URL, scanApiUrl: localNetStaticConfig.LOCALNET_SCAN_API_URL, auth: TOKEN_PROVIDER_CONFIG_DEFAULT, registryUrl: localNetStaticConfig.LOCALNET_REGISTRY_API_URL, }

export const ASSET_CONFIG: AssetConfig = { registries: [localNetStaticConfig.LOCALNET_REGISTRY_API_URL], auth: TOKEN_PROVIDER_CONFIG_DEFAULT, }

</div>

## Listing assets

The asset namespace provides a `list` getter to retrieve all assets from configured registries.

<div className="before-after">
```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
// v0 - manually fetch from token standard service
const tokenStandardService = new TokenStandardService(
    provider, logger, auth, false
)
const assetList = await tokenStandardService.registriesToAssets(
    registries.map((url) => url.href)
)

---

const assetList = sdk.asset.list

const amuletAsset = await sdk.asset.find('Amulet')

const amuletAsset = await sdk.asset.find(
    'Amulet',
    new URL('https://registry.example.com')
)

try {
    const unknownAsset = await sdk.asset.find('NonExistentAsset')
} catch (error) {
    // SDKError with type 'NotFound'
    // message: 'Asset with id NonExistentAsset not found'
}

try {
    const duplicateAsset = await sdk.asset.find('CommonAsset')
} catch (error) {
    // SDKError with type 'BadRequest'
    // message: 'Multiple assets found, please provide a registryUrl'
}

```typescript theme={"theme":{"light":"github-light","dark":"github-dark"}} import pino from 'pino' import { localNetStaticConfig, SDK } from '@canton-network/wallet-sdk' import path from 'path' import { fileURLToPath } from 'url' import fs from 'fs/promises' import { KeyPair } from '@canton-network/core-signing-lib' import { ASSET_CONFIG } from './utils/index.js' import { GenerateTransactionResponse } from '@canton-network/core-ledger-client' import { TOKEN_NAMESPACE_CONFIG, TOKEN_PROVIDER_CONFIG_DEFAULT, AMULET_NAMESPACE_CONFIG, } from './utils/index.js'

const logger = pino({ name: ‘v1-token-standard-allocation’, level: ‘info’ })

type PartyInfo = Omit<GenerateTransactionResponse, ‘topologyTransactions’> & { topologyTransactions?: string[] | undefined keyPair: KeyPair }

const sdk = await SDK.create({ auth: TOKEN_PROVIDER_CONFIG_DEFAULT, ledgerClientUrl: localNetStaticConfig.LOCALNET_APP_USER_LEDGER_URL, token: TOKEN_NAMESPACE_CONFIG, amulet: AMULET_NAMESPACE_CONFIG, asset: ASSET_CONFIG, })

// This example needs uploaded .dar for splice-token-test-trading-app // It’s in files of localnet, but it’s not uploaded to participant, so we need to do this in the script // Adjust if to your .localnet location const PATH_TO_LOCALNET = ’../../../../.localnet’ const PATH_TO_DAR_IN_LOCALNET = ‘/dars/splice-token-test-trading-app-1.0.0.dar’ const TRADING_APP_PACKAGE_ID = ‘e5c9847d5a88d3b8d65436f01765fc5ba142cc58529692e2dacdd865d9939f71’

const here = path.dirname(fileURLToPath(import.meta.url))

const tradingDarPath = path.join( here, PATH_TO_LOCALNET, PATH_TO_DAR_IN_LOCALNET )

//upload dar const darBytes = await fs.readFile(tradingDarPath) await sdk.ledger.dar.upload(darBytes, TRADING_APP_PACKAGE_ID)

//allocate parties const allocatedParties = await Promise.all( [‘v1-04-alice’, ‘v1-04-bob’, ‘v1-04-venue’].map(async (partyHint) => { const partyKeys = sdk.keys.generate() const party = await sdk.party.external .create(partyKeys.publicKey, { partyHint, }) .sign(partyKeys.privateKey) .execute()

      return [
          partyHint,
          {
              partyId: party.partyId,
              publicKeyFingerprint: party.publicKeyFingerprint,
              multiHash: party.multiHash,
              topologyTransactions: party.topologyTransactions,
              keyPair: partyKeys,
          },
      ] as const
  })

)

const partyInfo: Map<string, PartyInfo> = new Map(allocatedParties)

const sender = partyInfo.get(‘v1-04-alice’)! const recipient = partyInfo.get(‘v1-04-bob’)! const venue = partyInfo.get(‘v1-04-venue’)!

// Mint holdings for alice

const [amuletTapCommand, amuletTapDisclosedContracts] = await sdk.amulet.tap( sender.partyId, ‘2000000’ )

await sdk.ledger .prepare({ partyId: sender.partyId, commands: amuletTapCommand, disclosedContracts: amuletTapDisclosedContracts, }) .sign(sender.keyPair.privateKey) .execute({ partyId: sender.partyId })

// Mint holdings for bob

const [amuletTapCommandBob, amuletTapDisclosedContractsBob] = await sdk.amulet.tap(recipient.partyId, ‘2000000’)

await sdk.ledger .prepare({ partyId: recipient.partyId, commands: amuletTapCommandBob, disclosedContracts: amuletTapDisclosedContractsBob, }) .sign(recipient.keyPair.privateKey) .execute({ partyId: recipient.partyId })

//Alice creates OTCTradeProposal

const amuletAsset = await sdk.asset.find( ‘Amulet’, localNetStaticConfig.LOCALNET_REGISTRY_API_URL )

const transferLegs = { leg0: { sender: sender.partyId, receiver: recipient.partyId, amount: ‘100’, instrumentId: { admin: amuletAsset.admin, id: ‘Amulet’ }, meta: { values: {} }, }, leg1: { sender: recipient.partyId, receiver: sender.partyId, amount: ‘20’, instrumentId: { admin: amuletAsset.admin, id: ‘Amulet’ }, meta: { values: {} }, }, }

const createProposal = { CreateCommand: { templateId: ‘#splice-token-test-trading-app:Splice.Testing.Apps.TradingApp:OTCTradeProposal’, createArguments: { venue: venue.partyId, tradeCid: null, transferLegs, approvers: [sender.partyId], }, }, }

await sdk.ledger .prepare({ partyId: sender.partyId, commands: createProposal, disclosedContracts: [], }) .sign(sender.keyPair.privateKey) .execute({ partyId: sender.partyId })

logger.info( ‘OTC Trade Proposal created by Alice, ready for Bob to accept OTCTradeProposal’ )

// Bob accepts OTCTradeProposal

const activeTradeProposals = await sdk.ledger.acsReader.readJsContracts({ templateIds: [ ‘#splice-token-test-trading-app:Splice.Testing.Apps.TradingApp:OTCTradeProposal’, ], parties: [recipient.partyId], filterByParty: true, })

const otcpCid = activeTradeProposals[0].contractId

if (otcpCid === undefined) { throw new Error(‘Unexpected lack of OTCTradeProposal contract’) } const acceptCmd = [ { ExerciseCommand: { templateId: ‘#splice-token-test-trading-app:Splice.Testing.Apps.TradingApp:OTCTradeProposal’, contractId: otcpCid, choice: ‘OTCTradeProposal_Accept’, choiceArgument: { approver: recipient.partyId }, }, }, ]

await sdk.ledger .prepare({ partyId: recipient.partyId, commands: acceptCmd, disclosedContracts: [], }) .sign(recipient.keyPair.privateKey) .execute({ partyId: recipient.partyId })

logger.info(‘Bob accepted OTCTradeProposal’)

//Venue initiates settlement of OTCTradeProposal

const activeTradeProposals2 = await sdk.ledger.acsReader.readJsContracts({ templateIds: [ ‘#splice-token-test-trading-app:Splice.Testing.Apps.TradingApp:OTCTradeProposal’, ], parties: [venue.partyId], filterByParty: true, })

const now = new Date() const prepareUntil = new Date(now.getTime() + 60 * 60 * 1000).toISOString() const settleBefore = new Date(now.getTime() + 2 * 60 * 60 * 1000).toISOString()

const otcpCid2 = activeTradeProposals2[0].contractId

const initiateSettlementCmd = [ { ExerciseCommand: { templateId: ‘#splice-token-test-trading-app:Splice.Testing.Apps.TradingApp:OTCTradeProposal’, contractId: otcpCid2, choice: ‘OTCTradeProposal_InitiateSettlement’, choiceArgument: { prepareUntil, settleBefore }, }, }, ]

await sdk.ledger .prepare({ partyId: venue.partyId, commands: initiateSettlementCmd, disclosedContracts: [], }) .sign(venue.keyPair.privateKey) .execute({ partyId: venue.partyId })

logger.info(‘Venue initated settlement of OTCTradeProposal’)

const otcTrades = await sdk.ledger.acsReader.readJsContracts({ templateIds: [ ‘#splice-token-test-trading-app:Splice.Testing.Apps.TradingApp:OTCTrade’, ], parties: [venue.partyId], filterByParty: true, })

const otcTradeCid = otcTrades[0].contractId if (!otcTradeCid) throw new Error(‘OTCTrade not found for venue’)

logger.info({ otcTradeCid }, OtcTrades were found)

const pendingAllocationRequestsAlice = await sdk.token.allocation.request.pending(sender.partyId)

const allocationRequestViewAlice = pendingAllocationRequestsAlice?.[0].interfaceViewValue!

const legIdAlice = Object.keys(allocationRequestViewAlice.transferLegs).find( (key) => allocationRequestViewAlice.transferLegs[key].sender === sender.partyId )! if (!legIdAlice) throw new Error(No leg found for Alice)

const legAlice = allocationRequestViewAlice.transferLegs[legIdAlice]

const specAlice = { settlement: allocationRequestViewAlice.settlement, transferLegId: legIdAlice, transferLeg: legAlice, }

//TODO: go over if we should pass in expectedAdmin or instrumentId/registryUrl

const [allocateCmdAlice, allocateDisclosedAlice] = await sdk.token.allocation.instruction.create({ allocationSpecification: specAlice, asset: amuletAsset, })

await sdk.ledger .prepare({ partyId: sender.partyId, commands: allocateCmdAlice, disclosedContracts: allocateDisclosedAlice, }) .sign(sender.keyPair.privateKey) .execute({ partyId: sender.partyId })

logger.info(‘Alice created Allocation for her TransferLeg’)

const pendingAllocationRequestsBob = await sdk.token.allocation.request.pending( recipient.partyId )

const allocationRequestViewBob = pendingAllocationRequestsBob?.[0].interfaceViewValue!

const legIdBob = Object.keys(allocationRequestViewAlice.transferLegs).find( (key) => allocationRequestViewAlice.transferLegs[key].sender === recipient!.partyId )! if (!legIdBob) throw new Error(No leg found for Bob)

const legBob = allocationRequestViewAlice.transferLegs[legIdBob]

const specBob = { settlement: allocationRequestViewBob.settlement, transferLegId: legIdBob, transferLeg: legBob, }

//TODO: go over if we should pass in expectedAdmin or instrumentId/registryUrl

const [allocateCmdBob, allocateDisclosedBlice] = await sdk.token.allocation.instruction.create({ allocationSpecification: specBob, asset: amuletAsset, })

await sdk.ledger .prepare({ partyId: recipient.partyId, commands: allocateCmdBob, disclosedContracts: allocateDisclosedBlice, }) .sign(recipient.keyPair.privateKey) .execute({ partyId: recipient.partyId })

logger.info(‘Bob created Allocation for his TransferLeg’)

// Once the legs have been allocated, venue settles the trade triggering transfer of holdings

const allocationsVenue = await sdk.token.allocation.pending(venue.partyId)

const settlementRefId = allocationRequestViewAlice.settlement.settlementRef.id const relevantAllocations = allocationsVenue.filter( (a) => a.interfaceViewValue.allocation.settlement.executor === venue!.partyId && a.interfaceViewValue.allocation.settlement.settlementRef.id === settlementRefId )

if (relevantAllocations.length === 0) throw new Error(‘No matching allocations for this trade’)

const allocationEntries = await Promise.all( relevantAllocations.map(async (a) => { const cid = a.contractId const choiceContext = await sdk.token.allocation.context.execute({ allocationCid: cid, registryUrl: localNetStaticConfig.LOCALNET_REGISTRY_API_URL, })

      return {
          cid,
          legId: a.interfaceViewValue.allocation.transferLegId,
          extraArgs: {
              context: {
                  values: choiceContext.choiceContextData?.values ?? {},
              },
              meta: { values: {} },
          },
          disclosedContracts: choiceContext.disclosedContracts ?? [],
      }
  })

)

const allocationsWithContext: Record<string, { _1: string; _2: any }> = Object.fromEntries( allocationEntries.map((e) => [e.legId, { _1: e.cid, _2: e.extraArgs }]) )

const uniqueDisclosedContracts = Array.from( new Map( allocationEntries .flatMap((e) => e.disclosedContracts) .map((d: any) => [d.contractId, d]) ).values() )

const settleCmd = [ { ExerciseCommand: { templateId: ‘#splice-token-test-trading-app:Splice.Testing.Apps.TradingApp:OTCTrade’, contractId: otcTradeCid, choice: ‘OTCTrade_Settle’, choiceArgument: { allocationsWithContext }, }, }, ]

await sdk.ledger .prepare({ partyId: venue.partyId, commands: settleCmd, disclosedContracts: uniqueDisclosedContracts, }) .sign(venue.keyPair.privateKey) .execute({ partyId: venue.partyId })

logger.info( ‘Venue settled the OTCTrade, holdings are transfered to Alice and Bob’ )

await sdk.token.utxos .list({ partyId: sender.partyId, }) .then((transactions) => { logger.info( transactions, ‘Token Standard Holding Transactions (Alice):’ ) })

await sdk.token.utxos .list({ partyId: recipient.partyId, }) .then((transactions) => { logger.info(transactions, ‘Token Standard Holding Transactions (Bob):’) })

await sdk.token.holdings({ partyId: recipient.partyId }).then((allHoldings) => { logger.info(allHoldings, ‘List holding transactions (Bob)’) })

</div>

## Migration reference

| v0 approach                                 | v1 方法                                     |
| ------------------------------------------- | --------------------------------------------- |
| `tokenStandardService.registriesToAssets()` | `sdk.asset.list`                              |
| Manual array filtering for specific asset   | `asset.find(id, registryUrl?)`                |
| Manual 错误 handling for missing assets    | Built-in 错误 handling in `sdk.asset.find()` |

Asset-related 方法 migration

## See also

* `钱包-sdk-config` - SDK 配置
* `token-migration-v1` - Token namespace migration

---

> 本文由 CC Privacy Club 根据 Canton Network 官方文档（CC-BY-4.0）整理翻译，仅供学习；实现细节以官方最新版本为准。