Prove conformance on a live Canton node and document the project #23

Objective

Prove the token and the registry service actually work against a live Canton node, exercise the upstream CN Token Standard CLI against an instrument, and document the project well enough for a new contributor to run it.

Rationale

Everything to date is verified by Daml scripts and in-memory service tests. Neither touches a real participant, and the review already identified two concrete reasons the service would fail on a live node: the choice-context routes are configured with interface ids while the ledger client only ever builds a template filter, and the active-contract query runs at offset zero. Both are invisible to the current tests because the stubs return whatever they are given. Until a real node is in the loop, "green" means very little, and the standard-compliance claim is unproven until a registry-agnostic client reads our holdings.

Scope

In scope:

• A sandbox runbook and a seed script that produces an operator, a registry, and one instrument
• Fixing the interface-versus-template filter and the active-contract offset
• A guarded end-to-end transfer driven through the registry HTTP service
• Running @canton-network/token-standard-cli against a canton-token-forge instrument and recording the results
• AGENTS.md, docs/ARCHITECTURE.md, and an expanded README.md

Out of scope:

• Production deployment, container images, and orchestration manifests
• Performance and load testing
• Any new token feature

Architecture & technical considerations

• The end-to-end test must be guarded: green when a sandbox is reachable, skipped otherwise, so CI without a participant stays meaningful.
• The two live-node defects are entangled and should be resolved together with the environment variable naming, since the current *_INTERFACE_ID names actively mislead the operator into the broken configuration.
• The JSON Ledger API v2 envelope and AnyValue encoding have never been checked against a real node. Confirm them against the participant's own OpenAPI before assuming the client is correct.
• The CLI is registry-agnostic and reads the standard interfaces, so it should work against our instrument unchanged. If it does not, that is a conformance defect on our side.

Dependencies

Depends on the Daml token model and registry HTTP service epics. The two live-node defects block the end-to-end test and the CLI conformance check.

Issue breakdown

• Verify the JSON Ledger API v2 envelope and AnyValue encoding against a live node #45 Verify the JSON Ledger API v2 envelope and AnyValue encoding against a live node (spike, run first)
• Choice-context routes pass interface ids but the ledger client only builds template filters #39 Choice-context routes pass interface ids but the ledger client only builds template filters
• Active-contract queries run at offset 0 and return an empty set on a live node #40 Active-contract queries run at offset 0 and return an empty set on a live node
• Add a Canton sandbox runbook and seed script #41 Add a Canton sandbox runbook and seed script
• Drive an end-to-end transfer through the registry service against a sandbox #42 Drive an end-to-end transfer through the registry service against a sandbox
• Run the CN Token Standard CLI against an instrument and record conformance #43 Run the CN Token Standard CLI against an instrument and record conformance
• Bring the contributor documentation up to date with the shipped system #44 Write AGENTS.md and docs/ARCHITECTURE.md, and expand the README

Acceptance criteria

• A sandbox runbook and seed script exist and are documented
• A guarded end-to-end transfer test runs green against a live sandbox
• The token-standard CLI decodes our holdings and a completed transfer, with results recorded in docs/CONFORMANCE.md
• AGENTS.md, docs/ARCHITECTURE.md, and README.md onboard a fresh contributor
• The registry service works against a live participant with no code changes beyond configuration