gabitoesmiapodo · Oct 27, 2026 · Sep 4, 2026 · Sep 4, 2026 · Sep 4, 2026 · Sep 4, 2026
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1 @@
+*.dar binary
diff --git a/.gitignore b/.gitignore
@@ -22,6 +22,7 @@ typedoc/
 .env
 .env.local
 .env.fivenorth
+.env.registry
 
 # typescript
 *.tsbuildinfo

diff --git a/.lintstagedrc.mjs b/.lintstagedrc.mjs
@@ -1,9 +1,13 @@
+const examples = (files) => [...new Set(files.map((file) => file.match(/example-dapps\/[^/]+/)?.[0]))]
+
 export default {
   'canton-connect/src/**/*.{ts,tsx,js,jsx}': () => 'pnpm -C canton-connect test',
   'canton-dappbooster/src/**/*.{ts,tsx,js,jsx}': () => 'pnpm -C canton-dappbooster test',
   'example-dapps/*/src/**/*.{ts,tsx,js,jsx}': (files) =>
-    [...new Set(files.map((file) => file.match(/example-dapps\/[^/]+/)?.[0]))].map(
-      (example) => `pnpm -C ${example} test`,
+    examples(files).map((example) => `pnpm -C ${example} test`),
+  'example-dapps/*/{api,scripts}/**/*.{ts,mjs,sh}': (files) =>
+    examples(files).map(
+      (example) => `pnpm -C ${example} exec vitest run --passWithNoTests api scripts`,
     ),
   'canton-create/**/*.{ts,tsx,mjs,sh,json}': () => 'pnpm -C canton-create test',
   '{canton-create/scaffold/*/scripts,scripts}/*.{mjs,sh}': () =>

diff --git a/CLAUDE.md b/CLAUDE.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -39,6 +39,18 @@ The dApp runs on http://localhost:3012 and Wallet Gateway on http://localhost:30
 Connect through Wallet Gateway with `unsafe` as the client secret. Use `wallet-kernel` as the
 signing provider when creating parties.
 
+### Token Vesting dApp
+
+```bash
+pnpm dev:token-vesting        # interactive menu
+pnpm dev:token-vesting up     # LocalNet, both DARs, token registry, Wallet Gateway and dApp
+pnpm dev:token-vesting down   # stop everything and keep the ledger
+```
+
+The dApp runs on http://localhost:3012, its token registry on http://localhost:3013 and Wallet
+Gateway on http://localhost:3030. Both examples share the LocalNet, so stop one before you start the
+other.
+
 ## Before opening a pull request
 
 ```bash

diff --git a/architecture.md b/architecture.md
@@ -8,6 +8,7 @@
 | Wallet Gateway (external: [`canton-network/wallet`](https://github.com/canton-network/wallet)) | Node + Express + SQLite | The CIP-0103 wallet the dApp connects to: it holds the session, signs through the participant, and serves its own user UI. A root dev dependency, which `pnpm dev:amulet-vesting` runs on the host from `canton-create/scaffold/localnet/wallet-gateway.config.json` |
 | `scripts/` | Node + Bash + JSON | The root tooling: the doc, anatomy and version checks, the release bump, the `typedoc` configs and the gitleaks installer. See [`CLAUDE.md`](CLAUDE.md) |
 | `example-dapps/amulet-vesting/` | Vite + React + Ark UI + Tailwind v4 + `zustand` + react-router + Daml | Canton Coin **vesting** dApp, published as an example. Every read and write goes through the connected CIP-0103 wallet via `canton-connect`. Its `daml/` holds the `amulet-vesting` DAR: the vesting factory, proposal, contract and residual-claim templates. They hold real Canton Coin in escrow as a Splice `LockedAmulet`, and come vendored from [`BootNodeDev/cc-vesting-contracts`](https://github.com/BootNodeDev/cc-vesting-contracts). The build fetches its Splice data-dependencies rather than committing them. `scripts/bootstrap-vesting.mjs` creates the operator and its factory |
+| `example-dapps/token-vesting/` | Vite + React + Ark UI + Tailwind v4 + `zustand` + react-router | The same **vesting** dApp over a `DBT` instrument from [`BootNodeDev/canton-token-forge`](https://github.com/BootNodeDev/canton-token-forge), published as an example. Its `vesting` and `canton-token-forge` DARs ship as binaries in `vendor/`, so it builds no contract. `scripts/bootstrap-vesting.mjs` uploads them and creates the operator, its factory and the instrument; `scripts/registry.sh` runs the canton-token-forge registry the dApp reads the instrument from |
 | `canton-create/` | TypeScript + Ink + React 19 + `tsdown` | The `create-canton-dappbooster` installer. Its `scaffold/daml-tooling/` and `scaffold/localnet/` scripts are also the local loop: the Splice dependency fetch, the DAR build and upload, the token mint and `dev-stack.sh`. See [`canton-create/architecture.md`](canton-create/architecture.md) |
 | `canton-connect/` | TypeScript + React 19 | wagmi-style hooks wrapping the `dapp-sdk` facade |
 | `canton-dappbooster/` | TypeScript + React 19 + `tsdown` | L2 headless UI components, zero styling, plus the theme runtime and the pure utilities under the components, exact-decimal amounts included |
@@ -45,6 +46,11 @@ flowchart TD
 > connected party is a stakeholder of either. `transferContext.ts` reads both from Scan, at
 > `VITE_SCAN_API_URL`, and the browser makes those calls itself.
 
+`example-dapps/token-vesting` takes the same wallet path and has no Scan call. Its one call off the
+ledger goes to the canton-token-forge registry on `http://localhost:3013`, for the instrument and the
+`InstrumentConfig` each value-moving choice discloses. The registry reads the ledger with
+`CANTON_BACKEND_TOKEN`, as the scripts do.
+
 `app-user` is the primary local validator from the official Splice LocalNet
 bundle. It is not a product user. `sv` provides the Super Validator / DSO side
 needed by Splice and Canton Coin. The local stack does not start the app-provider
@@ -66,6 +72,7 @@ State boundaries:
 | --- | --- | --- |
 | dApp frontend | `http://localhost:3012` | example dApp |
 | Wallet Gateway | `http://localhost:3030` | the wallet: user UI, and `/api/v0/dapp` for the dApp |
+| Token registry | `http://localhost:3013` | the token example's canton-token-forge registry |
 | app-user Wallet UI | `http://wallet.localhost:2000` | optional official Splice wallet UI |
 | app-user Ledger API | `grpc://localhost:2901` | SDK/tools |
 | app-user administration API | `grpc://localhost:2902` | SDK/tools |
@@ -90,10 +97,9 @@ State boundaries:
 | `CANTON_AUTH_SECRET` | `.env` | unsafe local signing secret used only by the token script |
 | `CANTON_BACKEND_TOKEN` | `.env` | generated JWT consumed by the DAR upload and the vesting bootstrap |
 
-`example-dapps/amulet-vesting/.env` is the only one that matters: the signing recipe
-`mint-token.mjs` reads, plus the token `deploy-dar.sh` and the example's
-`scripts/bootstrap-vesting.mjs` send. The root scripts point the first two at it through
-`CANTON_APP_DIR`. Minting is offline, so it needs nothing running, which is what lets
+Each example's own `.env` is the one that matters: the signing recipe `mint-token.mjs` reads, plus
+the token `deploy-dar.sh` and the example's `scripts/bootstrap-vesting.mjs` send. The root scripts
+point the first two at it through `CANTON_APP_DIR`. Minting is offline, so it needs nothing running, which is what lets
 `pnpm dev:amulet-vesting up` mint `CANTON_BACKEND_TOKEN` into a fresh `.env` before anything is up. The
 LocalNet reads its own `canton-barebones.config.json`, which `dev-stack.sh` scaffolds into
 `.canton-localnet/` and git does not track.
@@ -113,6 +119,7 @@ that secret and nothing else.
 | --- | --- |
 | `pnpm dev:amulet-vesting up` | the whole local loop: LocalNet, DAR, bootstrap, Wallet Gateway, dApp dev server |
 | `pnpm dev:amulet-vesting down` | stop the gateway and the dApp dev server, stop the LocalNet |
+| `pnpm dev:token-vesting up` / `down` | the same loop on the token example, which also starts and stops its registry |
 | `pnpm run wallet-gateway` | the gateway alone, from `canton-create/scaffold/localnet/wallet-gateway.config.json` |
 | `pnpm exec canton-barebones start` / `stop` / `reset` / `status` | the LocalNet itself, run from `.canton-localnet/` |
 | `node canton-create/scaffold/localnet/scripts/localnet-config.mjs <dir>` | scaffold that directory and apply the flags nginx needs |
@@ -122,6 +129,10 @@ that secret and nothing else.
 | `pnpm run bootstrap` | create the vesting operator and its factory |
 | `pnpm run app:dev` | start the dApp frontend |
 
+`dev-stack.sh` runs an app's own `stack:up` script after `bootstrap` and its `stack:down` script on
+`down`, when the app defines them. The token example starts and stops its registry there, from
+the `.env.registry` its bootstrap writes.
+
 `dev-stack.sh` shells out to the LocalNet tool in the directory passed as its second argument
 (`pnpm dev:amulet-vesting up <dir>`). Otherwise it uses `CANTON_LOCALNET_DIR`, and then
 `.canton-localnet/`. It scaffolds that directory on `up` from the pinned tool's own template, and

diff --git a/biome.json b/biome.json
@@ -235,6 +235,16 @@
           }
         }
       }
+    },
+    {
+      "includes": ["**/scripts/**"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noRestrictedImports": "off"
+          }
+        }
+      }
     }
   ]
 }
diff --git a/canton-create/CLAUDE.md b/canton-create/CLAUDE.md
@@ -22,6 +22,9 @@ together, see [`architecture.md`](architecture.md).
   sets. Any other overwrite is a design error in `scaffold/`, and `scaffold` throws
   `ScaffoldConflictError`. So does any other field in a layer's `package.json`, apart from the
   layer's own `name`, `private`, `version` and `type`, because the merge would drop it.
+- What an app runs beside the ledger, such as the token example's registry, stays in the app. It
+  starts and stops through the app's own `stack:up` and `stack:down` scripts, which `dev-stack.sh`
+  runs when they exist, so the `localnet/` layer never learns about one app's services.
 - A layer's `README.md` is a section that gets appended, so it starts with a `##` heading and never
   with a title.
 - The root range rule has no exception in `scaffold/`: the tarball ships the folders as they are, so
@@ -30,7 +33,7 @@ together, see [`architecture.md`](architecture.md).
   `_pnpm-workspace.yaml`, and `scaffold` renames it back. npm drops a `.gitignore` from every
   tarball, and a `pnpm-workspace.yaml` inside the monorepo makes pnpm treat the folder as a
   workspace root of its own.
-- The monorepo runs the `daml-tooling/` and `localnet/` scripts on `example-dapps/amulet-vesting`
+- The monorepo runs the `daml-tooling/` and `localnet/` scripts on the examples in `example-dapps/`
   instead of keeping copies. Each script finds the app's `daml/` and `.env` through
   `CANTON_APP_DIR`, which defaults to its own project. A new script reads the app from there, never
   from a path to its own folder. Their tests sit beside them, and `files` keeps the tests out

diff --git a/canton-create/README.md b/canton-create/README.md
@@ -24,19 +24,22 @@ commit, and prints the next steps. If a step fails or you press Ctrl-C, it remov
 Alternatively, you can start with a preselected dApp or local network:
 
 - **Amulet Vesting:** a vesting dApp frontend and its contracts.
+- **Token Vesting:** a vesting dApp over a canton-token-forge token, with its registry.
 - **Barebones:** a minimal local Canton stack for developer workflows.
 
 With npm:
 
 ```shell
 npm create canton-dappbooster -- --example amulet-vesting   # Amulet Vesting dApp
+npm create canton-dappbooster -- --example token-vesting    # Token Vesting dApp
 npm create canton-dappbooster -- --localnet                 # Barebones local network
 ```
 
 With pnpm:
 
 ```shell
 pnpm create canton-dappbooster --example amulet-vesting   # Amulet Vesting dApp
+pnpm create canton-dappbooster --example token-vesting    # Token Vesting dApp
 pnpm create canton-dappbooster --localnet                 # Barebones local network
 ```
 
@@ -65,6 +68,7 @@ pnpm create canton-dappbooster my-dapp --example amulet-vesting --localnet   # A
 |---|---|---|---|
 | `Starter dApp` | none | ✓ | Barebones dApp that connects to a wallet and gives you a sample contract |
 | `Amulet Vesting` | `--example amulet-vesting` | | A vesting dApp frontend and its contracts |
+| `Token Vesting` | `--example token-vesting` | | A vesting dApp over a canton-token-forge token, with its registry |
 
 ### Local networks
 

diff --git a/canton-create/architecture.md b/canton-create/architecture.md
@@ -39,16 +39,16 @@ excludes.
 |---|---|---|
 | `starter/` | the dApp is the starter | the complete starter app and a sample contract in `daml/` |
 | `daml-tooling/` | the app has `daml/daml.yaml` | `build-dar`, `deploy-dar` and `fetch-daml-deps` |
-| `localnet/` | `--localnet` or Barebones | `dev-stack.sh`, `localnet-config.mjs`, `mint-token.mjs`, `wallet-gateway.config.json`, and `canton-barebones` and the gateway in `devDependencies` |
+| `localnet/` | `--localnet` or Barebones | `dev-stack.sh`, `localnet-config.mjs`, `mint-token.mjs`, `wallet-gateway.config.json`, and `canton-barebones` and the gateway in `devDependencies`. `dev-stack.sh` runs the app's own `bootstrap`, `stack:up` and `stack:down` scripts when it has them |
 
 `scaffold` in `src/scaffold.ts` copies the app first, then applies `daml-tooling/` and `localnet/`
 on top of it in that order. `src/merge.ts` decides how each layer file lands: merged into the
 manifest, appended, merged by key, or a conflict. `finalizeManifest` then strips what only a
 published package needs (`version`, `repository`, `files`, `publishConfig` and the rest), names the
 manifest after the folder and marks it private.
 
-The monorepo's own loop runs the same `daml-tooling/` and `localnet/` scripts on
-`example-dapps/amulet-vesting`, from the root `package.json`.
+The monorepo's own loop runs the same `daml-tooling/` and `localnet/` scripts on the examples in
+`example-dapps/`, from the root `package.json`.
 
 Each folder is a workspace package, so the monorepo checks their types against the libraries'
 source. Their ranges resolve as the Packaging section of the root

diff --git a/canton-create/demo.svg b/canton-create/demo.svg
diff --git a/canton-create/scaffold/localnet/README.md b/canton-create/scaffold/localnet/README.md
@@ -20,7 +20,8 @@ Then pick Wallet Gateway in the dApp's picker and log in with the client secret
 party in the gateway with `wallet-kernel` as the signing provider.
 
 On its first run, `pnpm stack up` mints `CANTON_BACKEND_TOKEN` into `.env`. When the project has a
-contract, it then builds and deploys it, and runs the `bootstrap` script if there is one. To
+contract, it then builds and deploys it. It runs the `bootstrap` script if there is one, then the
+`stack:up` script, which starts anything else the app needs. `pnpm stack down` runs `stack:down`. To
 wipe the ledger, run `canton-barebones reset` inside `.canton-localnet/`. You then have to create
 the gateway's parties again.
 

diff --git a/canton-create/scaffold/localnet/scripts/dev-stack.sh b/canton-create/scaffold/localnet/scripts/dev-stack.sh
@@ -4,8 +4,10 @@
 #
 # Every step is a script in package.json, which is the contract this file relies on:
 # `mint-token`, `wallet-gateway`, `dev`, `build-dar` and `deploy-dar` when the app has a contract
-# (daml/daml.yaml), and optionally `bootstrap`. `dev` and `bootstrap` are the app's own; the rest
-# run at the pnpm workspace root holding the app, which in a project is the same package.json.
+# (daml/daml.yaml), and optionally `bootstrap`, `stack:up` and `stack:down`. `dev`, `bootstrap`
+# and the two hooks are the app's own; the rest run at the pnpm workspace root holding the app,
+# which in a project is the same package.json. The hooks start and stop whatever else the app
+# runs beside the ledger, and get DEV_STACK_RUN_DIR for its logs.
 #
 # The LocalNet belongs to @bootnodedev/canton-barebones, pinned in
 # package.json and driven from the directory holding its config. `up` scaffolds that
@@ -117,7 +119,7 @@ die() {
 }
 
 # Keep in step with the `step` calls in up(), which are the list.
-STEP_TOTAL=$((8 + 2 * HAS_CONTRACT))
+STEP_TOTAL=$((9 + 2 * HAS_CONTRACT))
 STEP_INDEX=0
 STEP_NAME=stack
 STEP_START=$SECONDS
@@ -402,6 +404,10 @@ Fix what build-dar printed above, then run 'pnpm stack up' again (menu: Stack up
   step bootstrap "Running the bootstrap script, if the project defines one..."
   pnpm -C "$APP_DIR" run --if-present bootstrap || die "The bootstrap script failed."
 
+  step services "Starting the app's own services, if the project defines any..."
+  DEV_STACK_RUN_DIR="$RUN_DIR" pnpm -C "$APP_DIR" run --if-present stack:up 3>&- 4>&- \
+    || die "The stack:up script failed."
+
   step wallet-gateway "Starting the Wallet Gateway -> http://localhost:3030"
   start_wallet_gateway
 
@@ -469,6 +475,8 @@ stop_port() { # stop_port <port> <label>
 down() {
   # 1. Background processes
   stop_pidfile "$DAPP_PID" "dApp dev server"
+  DEV_STACK_RUN_DIR="$RUN_DIR" pnpm -C "$APP_DIR" run --if-present stack:down \
+    || warn "The stack:down script reported an error"
   stop_port 3012 "dApp dev server"
   stop_pidfile "$GW_PID" "Wallet Gateway"
   stop_port 3030 "Wallet Gateway"

diff --git a/canton-create/src/apps.ts b/canton-create/src/apps.ts
@@ -8,6 +8,10 @@ export const EXAMPLES: Record<string, Omit<RadioOption, 'value'>> = {
     label: 'Amulet Vesting',
     hint: 'A vesting dApp frontend and its contracts.',
   },
+  'token-vesting': {
+    label: 'Token Vesting',
+    hint: 'A vesting dApp over a canton-token-forge token, with its registry.',
+  },
 }
 
 /** Every dApp the list offers: the starter first, then the examples. */

diff --git a/canton-dappbooster/src/utils/readInstruments.ts b/canton-dappbooster/src/utils/readInstruments.ts
@@ -28,8 +28,15 @@ interface Page {
   nextPageToken: string | undefined
 }
 
+// A registry that accepts the socket and never answers would otherwise leave the caller's own
+// `await` pending for good, with nothing to render and no error to show for it.
+const REQUEST_TIMEOUT_MS = 15_000
+
 const get = async (url: string): Promise<unknown> => {
-  const response = await fetch(url, { headers: { accept: 'application/json' } })
+  const response = await fetch(url, {
+    headers: { accept: 'application/json' },
+    signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+  })
   if (!response.ok) {
     throw new Error(`${url} answered ${response.status}`)
   }
@@ -63,7 +70,8 @@ const toPage = (value: unknown): Page => {
  * Reads a registry's instrument metadata, following its pages up to a limit of 100, so the answer
  * is the registry's whole catalogue and a registry that will not stop paging cannot hang the caller.
  *
- * @throws where either request answers anything but 200, or the reply is not JSON.
+ * @throws where either request answers anything but 200, does not answer within 15s, or replies
+ * with something that is not JSON.
  *
  * @example
  * const instruments = await readInstruments('https://registry.example/api')

diff --git a/example-dapps/token-vesting/.env.example b/example-dapps/token-vesting/.env.example
@@ -0,0 +1,47 @@
+###############################################################################
+# Participant
+###############################################################################
+CANTON_JSON_API_URL=http://localhost:2975
+
+###############################################################################
+# Scripts / token generation
+###############################################################################
+CANTON_AUTH_AUDIENCE=https://canton.network.global
+# Never copy CANTON_AUTH_SECRET into a browser.
+CANTON_AUTH_SECRET=unsafe
+# On a LocalNet the stack fills this in; or run `pnpm mint-token`
+CANTON_BACKEND_TOKEN=
+
+# The token registry's own options, which scripts/registry.sh passes through to it when set here.
+# CORS_ORIGINS defaults to exactly http://localhost:3012, so the dApp opened on any other
+# spelling of that address (127.0.0.1, a published port, a LAN name) needs it listed here.
+# Quoted, and no space after the comma: dev-stack.sh sources this file as a shell script,
+# where an unquoted space starts a second word and aborts `up` before anything starts.
+#CORS_ORIGINS='http://localhost:3012,http://127.0.0.1:3012'
+
+###############################################################################
+# Frontend
+###############################################################################
+VITE_EXPLORER_URL=http://scan.localhost:4000
+VITE_REGISTRY_URL=http://localhost:3013
+VITE_WALLET_GATEWAY_URL=http://localhost:3030/api/v0/dapp
+
+###############################################################################
+# Wallet Connect
+###############################################################################
+VITE_NETWORK_ID=canton:local
+VITE_WALLET_CONNECT_PROJECT_ID=
+
+###############################################################################
+# Vercel
+###############################################################################
+# All three are set on the deployed project rather than in this file, and none can be localhost
+# there: the bundle asks its own origin for the registry, only the function names the registry,
+# and the gateway has to be one on the same network as that registry.
+#VITE_REGISTRY_URL=/api/registry
+#REGISTRY_URL=https://registry.example
+#VITE_WALLET_GATEWAY_URL=https://gateway.example/api/v0/dapp
+# Set by the build command in vercel.json, and by any other host that serves this
+# bundle: it is what makes the three URLs above required instead of falling back to localhost,
+# which an https page blocks as mixed content. Never set it for a local or CI build.
+#DEPLOYED_BUILD=1
diff --git a/example-dapps/token-vesting/AGENTS.md b/example-dapps/token-vesting/AGENTS.md
@@ -0,0 +1,3 @@
+# Agent Configuration
+This project's canonical agent configuration lives in [`CLAUDE.md`](./CLAUDE.md).
+Agents read `AGENTS.md` natively; load `CLAUDE.md` as the single source of truth.