feat: evolve the vesting dApp to Amulet on Splice LocalNet

.gitignore

@@ -5,6 +5,9 @@ node_modules/
 dist/
 dist-extension/
 
+# DAML build cache (per-package + multi-package root)
+**/.daml/
+
 # env
 .env
 .env.local

AGENTS.md

@@ -82,7 +82,7 @@ Subproject docs must not restate root rules. They should describe only their loc
   - `npm run build-dar -- <daml-project>` / `npm run deploy-dar -- <dar>`
   - `npm run carpincho:build:extension`
   - `npm run app:dev`
-- For local-stack convenience, [`scripts/dev-stack.sh`](scripts/dev-stack.sh) wraps the shortcuts above behind an interactive menu (run with no args) or direct subcommands (`install`, `docker-up`, `up`, `down`, `docker-down`, `mock-up`, `mock-down`, `extension`, `status`). The `npm` scripts remain canonical; the helper just orchestrates them. See [`README.md`](README.md).
+- For local-stack convenience, [`scripts/dev-stack.sh`](scripts/dev-stack.sh) wraps the shortcuts above behind an interactive menu (run with no args) or direct subcommands (`install`, `docker-up`, `up`, `down`, `amulet-up`, `amulet-down`, `docker-down`, `mock-up`, `mock-down`, `extension`, `status`). The `amulet-*` pair drives the Splice LocalNet stack (`:3020` proxy + dApp); LocalNet itself stays external (`canton builder`). The `npm` scripts remain canonical; the helper just orchestrates them. See [`README.md`](README.md).
 - Local ports are intentionally assigned in the `3010+` range (see table above). Do not change them without updating every subproject's defaults.
 - Treat the single root `package-lock.json` as authoritative. Do not regenerate it as part of unrelated changes, and do not reintroduce per-package lockfiles.
 - The root `package.json` pins `@canton-network/dapp-sdk` to `1.1.0` via `overrides`: consumers declare `^1.1.0`, but `1.2.0` is intentionally held back. npm 11 does not persist `overrides` into `package-lock.json`, so the pin is enforced by the override on every relock and by the resolved `1.1.0` entry in the lock on every plain install. Do not bump it without testing the dApp flow against the newer SDK.

README.md

@@ -79,6 +79,8 @@ Or call an action directly:
 | Docker down | `docker-down` | Quit Docker Desktop (macOS only). |
 | Stack up | `up` | Bring up containers, build + deploy the DAR, start the wallet (3011) and dApp (3012) dev servers, build the extension. |
 | Stack down | `down` | Stop the dev servers and tear down the containers. |
+| Amulet up | `amulet-up` | Splice LocalNet path: bootstrap parties/factory/funding, start the `:3020` wallet-service proxy, serve the dApp (3012). Assumes LocalNet is already booted. |
+| Amulet down | `amulet-down` | Stop the amulet proxy + dApp dev server (LocalNet is left running). |
 | Wallet up | `mock-up` | Start the mocked wallet-service (3010) + Carpincho web app (3011) with no Docker. |
 | Wallet down | `mock-down` | Stop the mocked wallet-service + Carpincho web app only. |
 | Build extension | `extension` | Build the Chrome extension and copy it to `~/Desktop/dist-extension`. |
@@ -87,6 +89,7 @@ Or call an action directly:
 Notes:
 
 - Docker lifecycle is managed separately from the stack: `up` and `down` assume Docker is already running and never start or quit it. Start/quit Docker with `docker-up` / `docker-down`, the Docker app, or your own CLI.
+- The `amulet-*` actions target the Splice LocalNet stack (ports 3020/3975/4000), not bare Canton. LocalNet is run by the external `canton builder` tool — the script preflights it but never boots or stops it. Boot it first with `canton builder start --validators app-provider` then `canton builder deploy canton-barebones/dars/amulet-vesting-0.0.1.dar`.
 - `up` requires Docker running and `dpm` on `PATH` (for the DAR build). It fails fast with a clear message if the daemon is not reachable.
 - Background dev-server PIDs and logs live under `${TMPDIR:-/tmp}/cn-dev-stack/`.
 - The two Docker actions are macOS only; on other platforms they warn and no-op, while every other action runs unchanged.

canton-barebones/wallet-service/src/config.ts

@@ -19,6 +19,8 @@ export interface WalletServiceConfig {
     jsonApiUrl: string
     ledgerApiUrl: string
     adminApiUrl: string
+    scanUrl: string
+    scanHost: string
     backendUserId: string
     backendToken?: string
     tokenSource: TokenSource
@@ -86,6 +88,8 @@ export const loadConfig = (): WalletServiceConfig => {
       jsonApiUrl: optional('CANTON_JSON_API_URL') ?? 'http://localhost:3013',
       ledgerApiUrl: optional('CANTON_LEDGER_API_URL') ?? 'grpc://localhost:3014',
       adminApiUrl: optional('CANTON_ADMIN_API_URL') ?? 'grpc://localhost:3015',
+      scanUrl: optional('CANTON_SCAN_URL') ?? 'http://localhost:4000',
+      scanHost: optional('CANTON_SCAN_HOST') ?? 'scan.localhost',
       backendUserId,
       backendToken: resolved.token,
       tokenSource: resolved.source,

canton-barebones/wallet-service/src/rpc.ts

@@ -1,3 +1,5 @@
+import * as http from 'node:http'
+import * as https from 'node:https'
 import { SDK } from '@canton-network/wallet-sdk'
 import type { WalletServiceConfig } from './config.ts'
 import type {
@@ -11,6 +13,7 @@ import type {
   LedgerApiRequest,
   Network,
   Provider,
+  ScanApiRequest,
   StatusEvent,
   Wallet,
 } from './types.ts'
@@ -347,6 +350,67 @@ export const createRpc = (config: WalletServiceConfig): Rpc => {
     return parsed
   }
 
+  // Transparent proxy to the Splice scan service. Returns raw parsed JSON from
+  // the scan service with no Authorization header — the scan service is public.
+  // Uses node:http directly so the Host header is actually sent; undici/fetch
+  // silently drops Host (it's a forbidden header), which breaks nginx vhost routing.
+  const scanApi = async (params: unknown): Promise<unknown> => {
+    const p = objectParam<ScanApiRequest>(params, 'scanApi')
+    if (typeof p.resource !== 'string' || p.resource.length === 0) {
+      throw new InvalidParams('resource is required')
+    }
+    const method = (p.requestMethod ?? 'post').toUpperCase()
+    const payload =
+      method !== 'GET' && method !== 'HEAD' && p.body !== undefined
+        ? JSON.stringify(p.body)
+        : undefined
+    const target = new URL(config.canton.scanUrl.replace(/\/$/, '') + p.resource)
+    // node:http(s) directly (not fetch) so the Host header survives for nginx vhost
+    // routing. Pick the transport + default port from the URL scheme so an https
+    // scanUrl is not silently sent as cleartext to port 80.
+    const isHttps = target.protocol === 'https:'
+    const transport = isHttps ? https : http
+    return new Promise<unknown>((resolve, reject) => {
+      const req = transport.request(
+        {
+          hostname: target.hostname,
+          port: target.port || (isHttps ? 443 : 80),
+          path: target.pathname + target.search,
+          method,
+          headers: {
+            'content-type': 'application/json',
+            host: config.canton.scanHost,
+            ...(payload !== undefined ? { 'content-length': Buffer.byteLength(payload) } : {}),
+          },
+        },
+        (res) => {
+          const chunks: Buffer[] = []
+          res.on('data', (chunk: Buffer) => chunks.push(chunk))
+          res.on('end', () => {
+            const text = Buffer.concat(chunks).toString('utf8')
+            const contentType = res.headers['content-type'] ?? ''
+            const isJson = text.length > 0 && contentType.includes('json')
+            const parsed: unknown = isJson ? safeJsonParse(text) : text
+            const status = res.statusCode ?? 0
+            if (status < 200 || status >= 300) {
+              const detail = typeof parsed === 'string' ? parsed : JSON.stringify(parsed)
+              reject(new Error(`Scan API ${method} ${p.resource} → HTTP ${status}: ${detail}`))
+            } else {
+              resolve(parsed)
+            }
+          })
+          res.on('error', reject)
+        },
+      )
+      req.setTimeout(15_000, () => req.destroy(new Error('Scan API timed out')))
+      req.on('error', reject)
+      if (payload !== undefined) {
+        req.write(payload)
+      }
+      req.end()
+    })
+  }
+
   // Reads the backend user's CanActAs rights (what the bootstrap grants), optionally
   // narrowed to a hint prefix so a long-lived dev ledger's stale grants don't leak in.
   const listAccounts = async (): Promise<Wallet[]> => {
@@ -417,6 +481,8 @@ export const createRpc = (config: WalletServiceConfig): Rpc => {
           return rpcResult(id, await executePrepared(request.params))
         case 'ledgerApi':
           return rpcResult(id, await ledgerApi(request.params))
+        case 'scanApi':
+          return rpcResult(id, await scanApi(request.params))
         case 'prepareExecute':
         case 'prepareExecuteAndWait':
         case 'signMessage':
@@ -458,6 +524,7 @@ export const createRpc = (config: WalletServiceConfig): Rpc => {
       'listAccounts',
       'getPrimaryAccount',
       'ledgerApi',
+      'scanApi',
       'prepareTransaction',
       'executePrepared',
     ],
@@ -469,6 +536,8 @@ export const createRpc = (config: WalletServiceConfig): Rpc => {
       jsonApiUrl: config.canton.jsonApiUrl,
       ledgerApiUrl: config.canton.ledgerApiUrl,
       adminApiUrl: config.canton.adminApiUrl,
+      scanUrl: config.canton.scanUrl,
+      scanHost: config.canton.scanHost,
       backendUserId: config.canton.backendUserId,
       hasBackendToken: config.canton.backendToken !== undefined,
     },

canton-barebones/wallet-service/src/types.ts

@@ -97,6 +97,12 @@ export type LedgerApiRequest = {
 
 export type LedgerApiResult = Record<string, unknown>
 
+export type ScanApiRequest = {
+  resource: string
+  requestMethod?: 'get' | 'post'
+  body?: unknown
+}
+
 export type SignMessageRequest = { message: string }
 export type SignMessageResult = { signature: string }
 

canton-barebones/wallet-service/test/rpc.test.ts

@@ -1,4 +1,5 @@
 import { strict as assert } from 'node:assert'
+import * as http from 'node:http'
 import { describe, it } from 'node:test'
 import { createRpc, errorData, errorMessage } from '../src/rpc.ts'
 import type { JsonRpcResponse } from '../src/types.ts'
@@ -18,6 +19,8 @@ const baseConfig = () => ({
     jsonApiUrl: 'http://localhost:3013',
     ledgerApiUrl: 'grpc://localhost:3014',
     adminApiUrl: 'grpc://localhost:3015',
+    scanUrl: 'http://localhost:4000',
+    scanHost: 'scan.localhost',
     backendUserId: 'wallet-service',
     backendToken: undefined as string | undefined,
     tokenSource: 'none' as const,
@@ -287,6 +290,57 @@ describe('party methods are off the dapp-api surface', () => {
   })
 })
 
+describe('scanApi pass-through', () => {
+  it('forwards to scanUrl + resource with Host header and returns parsed body', async () => {
+    const responseBody = { rounds: [{ number: 1 }] }
+    let capturedHost: string | undefined
+    let capturedAuth: string | undefined
+
+    const server = http.createServer((req, res) => {
+      capturedHost = req.headers.host
+      capturedAuth = req.headers.authorization
+      res.writeHead(200, { 'content-type': 'application/json' })
+      res.end(JSON.stringify(responseBody))
+    })
+
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+    const { port } = server.address() as { port: number }
+
+    const config = baseConfig()
+    config.canton.scanUrl = `http://127.0.0.1:${port}`
+
+    try {
+      const rpc = createRpc(config)
+      const res = (await rpc.handle({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'scanApi',
+        params: { resource: '/v0/domains/global-domain/rounds/open', requestMethod: 'get' },
+      })) as JsonRpcResponse
+      assert.ok('result' in res, `expected result, got: ${JSON.stringify(res)}`)
+      assert.deepEqual(res.result, responseBody)
+      assert.equal(capturedHost, 'scan.localhost')
+      assert.equal(capturedAuth, undefined)
+    } finally {
+      await new Promise<void>((resolve, reject) =>
+        server.close((err) => (err ? reject(err) : resolve())),
+      )
+    }
+  })
+
+  it('returns -32602 when resource is missing', async () => {
+    const rpc = createRpc(baseConfig())
+    const res = (await rpc.handle({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'scanApi',
+      params: { requestMethod: 'get' },
+    })) as JsonRpcResponse
+    assert.ok('error' in res)
+    assert.equal(res.error.code, -32602)
+  })
+})
+
 describe('ledgerApi pass-through', () => {
   it('accepts requestMethod=get', async () => {
     const rpc = createRpc(baseConfig())

dapp/daml/amulet-vesting/.gitignore

@@ -0,0 +1 @@
+.daml/

dapp/daml/amulet-vesting/daml.yaml

@@ -0,0 +1,21 @@
+# for config file options, refer to
+# https://docs.digitalasset.com/build/3.4/dpm/configuration.html#project-configuration
+# SDK pinned to 3.4.11 / LF target 2.1 to match the vendored Splice deps
+# (splice-amulet et al. are built with sdk 3.4.11 + --target=2.1). Keeping the
+# same SDK/LF as the deps lets the amulet-vesting-test package data-depend on this
+# DAR directly instead of recompiling the source at a different target.
+sdk-version: 3.4.11
+name: amulet-vesting
+source: daml
+version: 0.0.1
+dependencies:
+  - daml-prim
+  - daml-stdlib
+data-dependencies:
+  # paths are relative to this package dir (dapp/daml/amulet-vesting/); ../../ is dapp/ (the vendor root in this repo)
+  - ../../deps/splice-daml/dars/splice-amulet-0.1.19.dar
+  - ../../deps/splice-daml/dars/splice-api-token-holding-v1-1.0.0.dar
+  - ../../deps/splice-daml/dars/splice-api-token-metadata-v1-1.0.0.dar
+  - ../../deps/splice-daml/dars/splice-api-token-transfer-instruction-v1-1.0.0.dar
+build-options:
+  - --target=2.1