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

.yarnrc.yml

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

core/eslint-config/index.mjs

@@ -38,6 +38,7 @@ export function createConfig({ rootDir }) {
                 'damljs/**',
                 'docs/wallet-integration-guide/examples/**',
                 'examples/ping/playwright-report/**',
+                'examples/test-token-v1-registry/src/openapi-ts/**',
                 'core/rpc-generator/templates/client/typescript/src/index.ts',
             ],
         },

core/test-token/src/commands.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025-2026 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-import { TestTokenV1 } from 'src'
+import { TestTokenV1 } from './token'
 import {
     Allocation,
     AllocationFactory,

core/test-token/src/index.ts

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

core/test-token/src/token.ts

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

core/token-standard/src/generated-clients/index.ts

@@ -0,0 +1,7 @@
+// Copyright (c) 2025-2026 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export * as AllocationInstructionV1 from './splice-api-token-allocation-instruction-v1/allocation-instruction-v1'
+export * as AllocationV1 from './splice-api-token-allocation-v1/allocation-v1'
+export * as MetadataV1 from './splice-api-token-metadata-v1/token-metadata-v1'
+export * as TransferInstructionV1 from './splice-api-token-transfer-instruction-v1/transfer-instruction-v1'

core/token-standard/src/index.ts

@@ -4,5 +4,6 @@
 export * from './token-standard-client.js'
 export * from './interface-ids.const.js'
 export * from './types'
+export * as OffLedger from './generated-clients/index.js'
 
 export * from '@daml.js/token-standard-models-1.0.0'

core/wallet-test-utils/src/signing-provider-mocks/server.ts

@@ -3,6 +3,15 @@
 
 import * as http from 'node:http'
 
+type BodyChunk = Buffer | string | Uint8Array
+
+interface BodyReadableRequest {
+    method?: string | undefined
+    on(event: 'data', listener: (chunk: BodyChunk) => void): this
+    on(event: 'end', listener: () => void): this
+    on(event: 'error', listener: (error: Error) => void): this
+}
+
 export interface MockHttpResponse {
     status?: number
     body?: unknown
@@ -47,7 +56,7 @@ export interface SigningProviderMockServer {
     close(): Promise<void>
 }
 
-function readRawBody(req: http.IncomingMessage): Promise<string> {
+function readRawBody(req: BodyReadableRequest): Promise<string> {
     return new Promise((resolve, reject) => {
         const chunks: Buffer[] = []
         req.on('data', (chunk) => chunks.push(Buffer.from(chunk)))
@@ -58,7 +67,7 @@ function readRawBody(req: http.IncomingMessage): Promise<string> {
     })
 }
 
-async function parseRequestBody(req: http.IncomingMessage): Promise<unknown> {
+async function parseRequestBody(req: BodyReadableRequest): Promise<unknown> {
     if ((req.method ?? 'GET').toUpperCase() !== 'POST') {
         return {}
     }

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

@@ -0,0 +1,188 @@
+# @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
+
+- provides a reusable second CIP-0056 test token backend (beyond Amulet) so application tests do not become Amulet-specific
+- reduces duplication across teams by offering a shared, easy-to-deploy testing token instead of requiring each team to build a token from scratch
+- modernizes and harden the earlier prototype by aligning with current Wallet SDK usage and adding verification via automated tests
+- provides practical coverage of registry-facing CIP-0056 workflows to complement on-ledger-only token examples
+
+### App Logic Flow
+
+```mermaid
+flowchart LR
+  subgraph MAIN[Main request path]
+    direction LR
+    REQ[/HTTP Request/] --> APP[Registry App] --> ROUTER[Router] --> HANDLER[API handlers] --> RES[/HTTP Response/]
+  end
+
+  subgraph INIT[Startup and initialization]
+    direction TB
+    APP --> ADMIN[Admin initialization]
+    APP --> VET[DAR vetting in dev mode]
+  end
+
+  subgraph DEPS[Package dependencies]
+    direction TB
+    WSDK{{"@canton-network/wallet-sdk"}}
+    CORETEST{{"@canton-network/core-test-token"}}
+    CORESTD{{"@canton-network/core-token-standard"}}
+  end
+
+  WSDK --> ADMIN
+  WSDK --> VET
+  WSDK --> HANDLER
+  CORETEST --> HANDLER
+  CORESTD --> HANDLER
+```
+
+## 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:5634`.
+
+## 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
+
+## @customize Flag
+
+This example includes `@customize` comments in selected files.
+
+What it is for:
+
+- marks places that are intentionally project-specific
+- highlights decisions made for this reference implementation that you will likely want to change in your own token backend
+- acts as a migration checklist when copying this project into a new repository or package
+
+When to look it up:
+
+- right after copying/scaffolding this example for your own token
+- before first production-like deployment
+- when replacing test/demo behavior with your real business logic and infrastructure
+
+How to use it:
+
+1. Search the project for `@customize`.
+1. Review each marked location and decide whether to keep, replace, or remove that logic.
+1. Prioritize security, auth, persistence, and startup/init code paths first.
+
+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": {
+        "build": "tsdown --onSuccess \"tsc\"",
+        "dev": "NODE_ENV=development tsx --watch src/index.ts",
+        "clean": "tsc -b --clean; rm -rf dist",
+        "flatpack": "yarn pack --out \"$FLATPACK_OUTDIR\"",
+        "test": "vitest run --project node --project browser",
+        "test:coverage": "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",
+        "typescript": "^5.9.3",
+        "vitest": "^4.1.8"
+    },
+    "dependencies": {
+        "@canton-network/core-test-token": "workspace:^",
+        "@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",
+        "tsdown": "^0.22.12",
+        "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"
+    }
+}

examples/test-token-v1-registry/src/__test__/mocks.ts

@@ -0,0 +1,44 @@
+// Copyright (c) 2025-2026 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { vi } from 'vitest'
+
+const execute = vi.fn().mockResolvedValue({
+    completionOffset: 100,
+})
+const sign = vi.fn().mockReturnValue({ execute })
+const prepare = vi.fn().mockReturnValue({ sign })
+const create = vi.fn().mockReturnValue({ sign })
+
+const sdk = {
+    ledger: {
+        acsReader: {
+            readJsContracts: vi.fn(),
+        },
+        prepare,
+    },
+    keys: {
+        generate: vi.fn().mockReturnValue({
+            publicKey: 'test-public-key',
+            privateKey: 'test-private-key',
+        }),
+    },
+    testToken: {
+        create: {
+            rules: vi.fn(),
+        },
+    },
+    party: {
+        external: {
+            create,
+        },
+    },
+}
+
+export const mock = {
+    sdk,
+    prepare,
+    sign,
+    execute,
+    create,
+}