Demo App

The Sigilry demo app is a self-contained reference implementation that shows how a dApp talks to a wallet over the Canton network using typed JSON-RPC and the @sigilry/react hooks. It pairs a dApp pane with a wallet simulator pane so you can see the full discovery -> connect -> approval -> ledger flow, including the CIP-103 push events the wallet emits along the way.

Canton onboarding path

If you are new to Canton, follow this order:

1. DAML contract model (examples/demo-app/daml/TodoList.daml)
2. DAR + TypeScript generation ((cd examples/demo-app && dpm build -o dars/demo-todo-package-0.0.1.dar) then yarn --cwd examples/demo-app setup)
3. React + provider integration (examples/demo-app/src/** using @sigilry/react)

This mirrors real Canton projects: contract model first, then typed client bindings, then UI and wallet flow.

Why it matters

• Demonstrates provider discovery (useDiscovery + WalletPicker + a controlled provider) in a safe, local environment.
• Uses the same hooks and provider patterns you would use in production.
• Makes approvals and the full CIP-103 push-event surface (accountsChanged, statusChanged, txChanged, and the connected login event) visible so the data flow is easy to follow.

Quick start (demo app)

From the repo root:

nix develop
yarn install
yarn --cwd examples/demo-app dev

yarn --cwd examples/demo-app dev runs setup first (builds dependencies and regenerates bindings), then starts:

• the local Canton sandbox bootstrap flow (yarn dev:ledger)
• the Vite frontend (yarn dev:frontend)

Open http://localhost:5173 and:

1. Pick a wallet in the Discover a wallet picker (the demo injects one simulated wallet).
2. Click Connect wallet.
3. Click Create TodoList (if no active factory exists).
4. Add a todo and approve the request in the wallet pane.
5. Observe the ledger update and the events in the RPC & Events panel.

Verify startup success

After yarn --cwd examples/demo-app dev, you should see:

• Frontend available at http://localhost:5173.
• Wallet pane status transitions from loading to ready.
• Connect button works and account details appear.
• Terminal ledger process remains running without immediate crash.

If you changed contracts and want to refresh the committed DAR first:

(cd examples/demo-app && dpm build -o dars/demo-todo-package-0.0.1.dar)
yarn --cwd examples/demo-app setup

Useful logs and files

• Ledger runtime logs: examples/demo-app/log/canton.log
• Bootstrap logs: examples/demo-app/log/canton-bootstrap.log
• Bootstrap stderr: examples/demo-app/log/bootstrap-stderr.log
• Frontend debug logs: browser devtools console (console.debug)

What the panes represent

• Left pane: the dApp UI, gated by a discovery WalletPicker and then driven by @sigilry/react hooks (useConnect, useAccounts, useSubmitCommand). The RPC & Events panel logs the provider’s push events.
• Right pane: an in-browser wallet simulator that injects window.canton, queues approvals, and emits provider events.

Provider discovery

The dApp does not reach for window.canton directly. Instead it gates on discovery, mirroring the pattern in @sigilry/react and Provider Discovery:

• useDiscovery() returns the wallets that announced over canton:announceProvider, falling back to the injected window.canton when none have.
• WalletPicker renders that list; selecting one calls wallet.getProvider().
• The chosen provider is passed to CantonReactProvider’s controlled provider prop, binding every hook below it to that wallet.

The demo injects a single simulated wallet, so the picker shows one entry (“Injected Canton Provider”). In a real deployment each installed wallet extension announces itself and the picker lists all of them.

Push events

The wallet simulator emits the full CIP-103 push-event surface, and the RPC & Events panel renders each as it arrives:

• accountsChanged, statusChanged, txChanged — the CIP-103 §4.2.2 sync events.
• connected — the separate login-flow event (not one of the §4.2.2 three).

Most apps consume these indirectly through useAccounts, useSession, and useConnect; the panel subscribes to the raw useCanton() helpers (onAccountsChanged, onStatusChanged, onTxChanged, onConnected) purely to make the transitions visible.

Flow walkthrough

• Discover wallet: useDiscovery lists available wallets; selecting one binds it via CantonReactProvider.
• Connect wallet: useConnect issues request({ method: "connect" }), the wallet emits connected, and accounts load.
• Create todo: useSubmitCommand calls TodoList.AddItem; the wallet pane receives an approval request.
• Approve: mock wallet resolves request, mock ledger applies command, provider emits txChanged.
• Refresh UI: useActiveContracts picks up updated contracts and re-renders todo items.

Nix-first tooling notes

• The workspace flake pins toolchain inputs for repeatable dpm and codegen behavior.
• Demo scripts call nix develop ../.. --command ..., so DAML/codegen commands run with the same toolchain.
• Keep DAML SDK and generated bindings in sync by rerunning (cd examples/demo-app && dpm build -o dars/demo-todo-package-0.0.1.dar) and then yarn --cwd examples/demo-app setup after contract edits.

First-run troubleshooting

• Ed25519 unsupported: use localhost/HTTPS and a browser with Web Crypto Ed25519.
• No accounts loaded: connect wallet first; account events are emitted after connect.
• No contract updates: rebuild DAR + regenerate bindings (setup), then reload the app.

Learn more

• Quick Start: how to wire a provider and connect.
• Provider Discovery: the discovery model behind useDiscovery and WalletPicker.
• RPC Protocol: typed JSON-RPC requests and events.
• @sigilry/react: hook reference and usage patterns.

For the full walkthrough, see the repository guide in examples/demo-app/README.md.