feat(example-test-token-v1-registry): create backend registry example

.vscode/extensions.json

@@ -1,8 +1,8 @@
 {
-    "recommendations": [
-        "arcanis.vscode-zipfs",
-        "dbaeumer.vscode-eslint",
-        "esbenp.prettier-vscode",
-        "runem.lit-plugin"
-    ]
+  "recommendations": [
+    "arcanis.vscode-zipfs",
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "runem.lit-plugin"
+  ]
 }

.yarnrc.yml

@@ -12,6 +12,10 @@ packageExtensions:
         dependencies:
             '@inquirer/prompts': ^3.0.0
             '@open-rpc/schema-utils-js': ^2.0.2
+    openapicmd@*:
+        dependencies:
+            indent-string: ^4.0.0
+            lodash: '*'
     undici-types@*:
         dependencies:
             '@types/node': '*'

core/token-standard/rollup.config.js

@@ -16,6 +16,11 @@ const DAML_JS_BASE = path.resolve(
     '../../damljs/token-standard-models'
 )
 
+const TEST_TOKEN_BASE = path.resolve(
+    import.meta.dirname,
+    '../../damljs/test-token-v1'
+)
+
 const DAML_JS_PACKAGES = {
     '@daml.js/token-standard-models-1.0.0': path.join(
         DAML_JS_BASE,
@@ -29,6 +34,30 @@ const DAML_JS_PACKAGES = {
         DAML_JS_BASE,
         'daml-stdlib-DA-Time-Types-1.0.0'
     ),
+    '@daml.js/test-token-v1': path.join(
+        TEST_TOKEN_BASE,
+        'splice-test-token-v1-1.0.0'
+    ),
+    '@daml.js/splice-api-token-allocation-instruction-v1-1.0.0': path.join(
+        TEST_TOKEN_BASE,
+        'splice-api-token-allocation-instruction-v1-1.0.0'
+    ),
+    '@daml.js/splice-api-token-transfer-instruction-v1-1.0.0': path.join(
+        TEST_TOKEN_BASE,
+        'splice-api-token-transfer-instruction-v1-1.0.0'
+    ),
+    '@daml.js/splice-api-token-holding-v1-1.0.0': path.join(
+        TEST_TOKEN_BASE,
+        'splice-api-token-holding-v1-1.0.0'
+    ),
+    '@daml.js/splice-api-token-allocation-v1-1.0.0': path.join(
+        TEST_TOKEN_BASE,
+        'splice-api-token-allocation-v1-1.0.0'
+    ),
+    '@daml.js/splice-api-token-metadata-v1-1.0.0': path.join(
+        TEST_TOKEN_BASE,
+        'splice-api-token-metadata-v1-1.0.0'
+    ),
 }
 
 function buildPathsMap(packageDirs) {

core/token-standard/src/index.ts

@@ -3,6 +3,6 @@
 
 export * from './token-standard-client.js'
 export * from './interface-ids.const.js'
-export * from './types'
-
+export * from './types.js'
+export * from './test-token.js'
 export * from '@daml.js/token-standard-models-1.0.0'

core/token-standard/src/test-token.ts

@@ -0,0 +1,9 @@
+// Copyright (c) 2025-2026 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Splice, packageId } from '@daml.js/test-token-v1'
+
+export const TestTokenV1 = {
+    ...Splice.Testing.Tokens.TestTokenV1,
+    packageId,
+}

core/token-standard/src/types.ts

@@ -23,13 +23,11 @@ export type {
 
 export type {
     Transfer,
-    TransferInstruction,
     TransferInstructionView,
     TransferInstruction_Accept,
     TransferInstruction_Reject,
     TransferInstruction_Withdraw,
     TransferInstruction_Update,
-    TransferFactory,
     TransferFactoryView,
     TransferFactory_PublicFetch,
     TransferFactory_Transfer,
@@ -40,6 +38,12 @@ export type {
     TransferInstructionInterface,
 } from '@daml.js/token-standard-models-1.0.0/lib/Splice/Api/Token/TransferInstructionV1/module.js'
 
+// Export companion objects as values (needed for accessing choice names at runtime)
+export {
+    TransferInstruction,
+    TransferFactory,
+} from '@daml.js/token-standard-models-1.0.0/lib/Splice/Api/Token/TransferInstructionV1/module.js'
+
 export type {
     AllocationFactory_Allocate,
     AllocationFactoryView,
@@ -49,12 +53,16 @@ export type {
     AllocationInstructionView,
     AllocationInstructionResult,
     AllocationInstructionResult_Output,
-    AllocationFactory,
     AllocationFactoryInterface,
-    AllocationInstruction,
     AllocationInstructionInterface,
 } from '@daml.js/token-standard-models-1.0.0/lib/Splice/Api/Token/AllocationInstructionV1/module.js'
 
+// Export companion objects as values (needed for accessing choice names at runtime)
+export {
+    AllocationFactory,
+    AllocationInstruction,
+} from '@daml.js/token-standard-models-1.0.0/lib/Splice/Api/Token/AllocationInstructionV1/module.js'
+
 export type {
     AllocationRequest,
     AllocationRequestView,
@@ -69,7 +77,6 @@ export type {
     SettlementInfo,
     Reference,
     AllocationView,
-    Allocation,
     AllocationInterface,
     Allocation_Withdraw,
     Allocation_Cancel,
@@ -79,6 +86,9 @@ export type {
     Allocation_ExecuteTransferResult,
 } from '@daml.js/token-standard-models-1.0.0/lib/Splice/Api/Token/AllocationV1/module.js'
 
+// Export companion object as value (needed for accessing choice names at runtime)
+export { Allocation } from '@daml.js/token-standard-models-1.0.0/lib/Splice/Api/Token/AllocationV1/module.js'
+
 export type {
     ExtraArgs,
     Metadata,

core/token-standard/tsconfig.json

@@ -23,6 +23,9 @@
             ],
             "@daml.js/daml-stdlib-DA-Time-Types-1.0.0/*": [
                 "../../damljs/token-standard-models/daml-stdlib-DA-Time-Types-1.0.0/*"
+            ],
+            "@daml.js/test-token-v1": [
+                "../../damljs/test-token-v1/splice-test-token-v1-1.0.0/lib/index.d.ts"
             ]
         }
     },

examples/test-token-v1-registry/README.md

@@ -0,0 +1,137 @@
+# @canton-network/example-test-token-v1-registry
+
+Example backend registry implementation for CIP-0056 token flows on Canton.
+
+## Overall Description
+
+This project is a reference implementation of a token registry backend for the Test Token V1 standard. It exposes registry API endpoints for:
+
+- token metadata
+- transfer instructions
+- allocations
+- allocation instructions
+
+Purpose:
+
+- provide a reusable second CIP-0056 test token backend (beyond Amulet) so application tests do not become Amulet-specific
+- reduce duplication across teams by offering a shared, easy-to-deploy testing token instead of requiring each team to build a token from scratch
+- modernize and harden the earlier prototype by aligning with current Wallet SDK usage and adding verification via automated tests
+- provide practical coverage of registry-facing CIP-0056 workflows to complement on-ledger-only token examples
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20+
+- Yarn 4.x
+- dependencies installed at repository root
+- local Canton/localnet setup if you want full end-to-end behavior
+
+### Installation
+
+From repository root:
+
+```bash
+yarn install
+```
+
+Build only this example:
+
+```bash
+yarn workspace @canton-network/example-test-token-v1-registry build
+```
+
+Run in development mode:
+
+```bash
+yarn workspace @canton-network/example-test-token-v1-registry dev
+```
+
+The API listens on `http://localhost:3000`.
+
+## Project Structure
+
+### Local Structure Overview
+
+```text
+examples/test-token-v1-registry/
+  src/
+    index.ts                          # app startup, admin init, dev vetting hook
+    router.ts                         # route prefix to API handler mapping
+    common/
+      sdk.ts                          # Wallet SDK bootstrap/auth
+      admin.ts                        # admin party initialization
+      vetDaml.ts                      # dev-only DAR vetting helper
+      getOpenApiPath.ts               # OpenAPI source path resolution
+    api/
+      metadata/                       # metadata endpoints + tests
+      transfer-instruction/           # transfer-instruction endpoints + tests
+      allocation/                     # allocation endpoints + tests
+      allocation-instruction/         # allocation-instruction endpoints + tests
+      common.ts                       # shared API context typing helpers
+    openapi-ts/                       # generated TypeScript types from OpenAPI
+    scripts/
+      generateTypes.ts                # regenerates openapi-ts bindings
+    __test__/
+      mocks.ts                        # test mocks
+  vitest.config.ts                    # node+browser test projects and coverage
+  tsup.config.ts                      # build configuration
+  tsconfig.json
+```
+
+## Testing
+
+Run tests:
+
+```bash
+yarn workspace @canton-network/example-test-token-v1-registry test
+```
+
+Run tests with coverage:
+
+```bash
+yarn workspace @canton-network/example-test-token-v1-registry test:coverage
+```
+
+Notes:
+
+- tests are discovered under `src/**/*.test.ts`
+- both node and browser projects are executed
+- coverage thresholds are defined in `vitest.config.ts`
+
+## Development & Contribution Guide
+
+Development loop:
+
+1. Modify API handlers and domain logic in `src/api/**`.
+2. If API specs change, regenerate types:
+
+    ```bash
+    yarn workspace @canton-network/example-test-token-v1-registry generate:types
+    ```
+
+3. Run tests and coverage.
+4. Build before opening a PR.
+
+General contribution guidelines for the monorepo: [Contributing Guide](https://github.com/canton-network/wallet/blob/main/docs/CONTRIBUTING.md)
+
+## 6. License
+
+Apache-2.0
+
+## 7. Additional Resources
+
+- [Wallet Repository](https://github.com/canton-network/wallet)
+- [dApp Building Documentation](https://github.com/canton-network/wallet/tree/main/docs/dapp-building)
+- [Wallet Integration Guide](https://github.com/canton-network/wallet/tree/main/docs/wallet-integration-guide)
+- [CIP Repository (including CIP-0056 context)](https://github.com/canton-foundation/cips)
+
+## 8. Bug Reporting
+
+If you find a bug:
+
+1. Open an issue at: [canton-network/wallet issues](https://github.com/canton-network/wallet/issues)
+1. Include reproduction steps, expected behavior, and actual behavior.
+1. Attach logs and relevant request/response payloads when possible.
+
+If issue templates are available in the repository, prefer using the most specific template.

examples/test-token-v1-registry/package.json

@@ -0,0 +1,66 @@
+{
+    "name": "@canton-network/example-test-token-v1-registry",
+    "version": "1.0.0",
+    "type": "module",
+    "description": "Example registry backend app for CIP-0056 token.",
+    "license": "Apache-2.0",
+    "author": "Mateusz Piątkowski <mateusz.piatkowski@digitalasset.com>",
+    "main": "dist/index.cjs",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js",
+            "require": "./dist/index.cjs",
+            "default": "./dist/index.js"
+        }
+    },
+    "scripts": {
+        "generate:types": "tsx ./src/scripts/generateTypes.ts",
+        "build": "yarn generate:types && tsup --onSuccess \"tsc\"",
+        "dev": "yarn generate:types && NODE_ENV=development tsx --watch src/index.ts",
+        "clean": "tsc -b --clean; rm -rf dist",
+        "flatpack": "yarn pack --out \"$FLATPACK_OUTDIR\"",
+        "test": "yarn generate:types && vitest run --project node --project browser",
+        "test:coverage": "yarn generate:types && vitest run --project node --project browser --coverage"
+    },
+    "devDependencies": {
+        "@types/koa": "^3",
+        "@types/koa-bodyparser": "^4",
+        "@types/lodash": "^4.17.24",
+        "@types/node": "^25.9.3",
+        "@vitest/browser-playwright": "^4.1.8",
+        "@vitest/coverage-v8": "^4.1.8",
+        "openapicmd": "^2.9.2",
+        "playwright": "^1.60.0",
+        "tsup": "^8.5.1",
+        "typescript": "^5.9.3",
+        "vitest": "^4.1.8"
+    },
+    "dependencies": {
+        "@canton-network/core-token-standard": "workspace:^",
+        "@canton-network/core-types": "workspace:^",
+        "@canton-network/wallet-sdk": "workspace:^",
+        "koa": "^3.2.1",
+        "koa-bodyparser": "^4.4.1",
+        "openapi-backend": "^5.18.0",
+        "tsx": "^4.23.0",
+        "zod": "^4.4.3"
+    },
+    "files": [
+        "dist/**"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/canton-network/wallet.git",
+        "directory": "examples/test-token-v1-registry"
+    },
+    "homepage": "https://github.com/canton-network/wallet/tree/main/examples/test-token-v1-registry#readme",
+    "bugs": {
+        "url": "https://github.com/canton-network/wallet/issues"
+    }
+}