create-partylayer-app 0.4.1 → 0.5.1

package/templates/react-dvp/src/sections/Trades.tsx

@@ -0,0 +1,298 @@
+/**
+ * Trades section (the DvP core). Role-aware over the same allocation requests.
+ *
+ * Counterparties (Alice, Bob) see the legs they send: each has an "Allocate my leg"
+ * action (CostPreview then useAllocationInstruction) and a "Reject" action
+ * (useAllocationRequestAction, action 'reject', actor = the current party).
+ *
+ * The venue sees a "New trade" form, per-leg allocation status (matched or missing
+ * via the expected-spec comparator over the counterparties' allocations), an atomic
+ * "Settle" (the generic useChoice; enabled only when every leg is matched), a
+ * "Withdraw trade" (useAllocationRequestAction, action 'withdraw'), and a per-matched
+ * -leg "Cancel allocation" (useAllocationAction, action 'cancel') for the abort path.
+ */
+import { useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import {
+  useAllocationRequests,
+  useTokenAllocations,
+  useAllocationInstruction,
+  useAllocationAction,
+  useAllocationRequestAction,
+  useChoice,
+  type AllocationInstructionRequest,
+} from '@partylayer/react/query';
+import { CostPreview, TransactionToast } from '@partylayer/react';
+import { useDemo, partyKey } from '../context/DemoContext';
+import { Card, AsyncView, Badge, Field } from '../ui/primitives';
+import { toastStatus } from '../lib/mutation';
+import { invalidateAll } from '../lib/invalidate';
+import { allocationForLeg, matchedLegIds } from '../lib/match';
+import { formatAmount, isPositiveAmount } from '../lib/format';
+import { PARTIES, REGISTRY, FEE_ESTIMATE } from '../lib/fixtures';
+import { demoStore } from '../lib/store';
+import type { SettleTrade, CreateTrade } from '../lib/types';
+
+export function Trades() {
+  const { party } = useDemo();
+  return party === 'venue' ? <VenueTrades /> : <CounterpartyTrades />;
+}
+
+function CounterpartyTrades() {
+  const { party, backend } = useDemo();
+  const queryClient = useQueryClient();
+  const me = PARTIES[party].partyId;
+  const [allocating, setAllocating] = useState<string | null>(null);
+
+  const trades = useAllocationRequests({
+    read: (signal) => backend.readTrades(signal),
+    key: partyKey('trades', party),
+  });
+
+  const allocate = useAllocationInstruction<{ ok: true }>({
+    submit: (request, signal) => backend.submitAllocation(request, signal),
+    mutation: { onSuccess: () => invalidateAll(queryClient) },
+  });
+
+  const reject = useAllocationRequestAction<{ ok: true }>({
+    submit: (request, signal) => backend.submitRequestAction(request, signal),
+    mutation: { onSuccess: () => invalidateAll(queryClient) },
+  });
+
+  const doAllocate = (requestCid: string, legId: string) => {
+    const trade = trades.requests?.find((t) => t.cid === requestCid);
+    if (!trade) return;
+    const leg = trade.request.transferLegs[legId];
+    const request: AllocationInstructionRequest = {
+      // SECURITY: expectedAdmin comes from a trusted source (here the registry
+      // constant); the choice checks the factory's admin against it.
+      expectedAdmin: REGISTRY,
+      allocation: {
+        settlement: trade.request.settlement,
+        transferLegId: legId,
+        transferLeg: leg,
+      },
+      requestedAt: new Date().toISOString(),
+      inputHoldingCids: demoStore.unlockedCids(party, leg.instrumentId.admin, leg.instrumentId.id),
+      meta: {},
+    };
+    setAllocating(requestCid + ':' + legId);
+    allocate.submitAllocation(request);
+  };
+
+  return (
+    <Card title="Trades" hint="useAllocationRequests + useAllocationInstruction + useAllocationRequestAction">
+      <AsyncView
+        isPending={trades.isPending}
+        error={trades.error}
+        data={trades.requests}
+        isEmpty={(items) => items.length === 0}
+        empty="No open trades."
+      >
+        {(items) => (
+          <ul className="list">
+            {items.map((trade) => {
+              const myLegs = Object.entries(trade.request.transferLegs).filter(
+                ([, leg]) => leg.sender === me,
+              );
+              return (
+                <li key={trade.cid} className="row row-block">
+                  <div className="row-main">
+                    <div className="row-title">
+                      Trade {trade.request.settlement.settlementRef.id}{' '}
+                      <span className="muted">executor {trade.request.settlement.executor}</span>
+                    </div>
+                    {Object.entries(trade.request.transferLegs).map(([legId, leg]) => (
+                      <div key={legId} className="row-sub muted">
+                        {legId}: {formatAmount(leg.amount)} {leg.instrumentId.id} from {leg.sender} to {leg.receiver}
+                      </div>
+                    ))}
+                  </div>
+                  {myLegs.length > 0 ? (
+                    <div className="leg-actions">
+                      {myLegs.map(([legId, leg]) => (
+                        <div key={legId} className="leg-action">
+                          <div className="row-sub">
+                            Your leg <Badge tone="neutral">{legId}</Badge>{' '}
+                            {formatAmount(leg.amount)} {leg.instrumentId.id}
+                          </div>
+                          <CostPreview estimate={FEE_ESTIMATE} />
+                          <div className="row-actions">
+                            <button
+                              className="btn btn-primary btn-small"
+                              disabled={allocate.isPending}
+                              onClick={() => doAllocate(trade.cid, legId)}
+                            >
+                              Allocate my leg
+                            </button>
+                            <button
+                              className="btn btn-ghost btn-small"
+                              disabled={reject.isPending}
+                              onClick={() => reject.submitAction({ requestCid: trade.cid, action: 'reject', actor: me })}
+                            >
+                              Reject
+                            </button>
+                          </div>
+                        </div>
+                      ))}
+                    </div>
+                  ) : (
+                    <div className="row-sub muted">No leg for you to allocate on this trade.</div>
+                  )}
+                </li>
+              );
+            })}
+          </ul>
+        )}
+      </AsyncView>
+
+      <TransactionToast
+        status={toastStatus(allocate)}
+        error={allocate.error}
+        message={allocate.isSuccess ? 'Allocated ' + (allocating ?? '') + '.' : undefined}
+      />
+      <TransactionToast
+        status={toastStatus(reject)}
+        error={reject.error}
+        message={reject.isSuccess ? 'Trade rejected.' : undefined}
+      />
+    </Card>
+  );
+}
+
+function VenueTrades() {
+  const { party, backend } = useDemo();
+  const queryClient = useQueryClient();
+
+  const trades = useAllocationRequests({
+    read: (signal) => backend.readTrades(signal),
+    key: partyKey('trades', party),
+  });
+  // The venue matches allocations against trade legs from the counterparties'
+  // allocation reads (party-scoped keys), then compares with the app comparator.
+  const aliceAllocs = useTokenAllocations({
+    read: (signal) => backend.readAllocations('alice', signal),
+    key: partyKey('allocations', 'alice'),
+  });
+  const bobAllocs = useTokenAllocations({
+    read: (signal) => backend.readAllocations('bob', signal),
+    key: partyKey('allocations', 'bob'),
+  });
+  const combined = [...(aliceAllocs.allocations ?? []), ...(bobAllocs.allocations ?? [])];
+
+  const createTrade = useChoice<{ ok: true }, CreateTrade>({
+    exercise: (vars) => backend.submitCreateTrade(vars),
+    mutation: { onSuccess: () => invalidateAll(queryClient) },
+  });
+  const settle = useChoice<{ ok: true }, SettleTrade>({
+    exercise: (vars) => backend.submitSettle(vars),
+    mutation: { onSuccess: () => invalidateAll(queryClient) },
+  });
+  const requestAction = useAllocationRequestAction<{ ok: true }>({
+    submit: (request, signal) => backend.submitRequestAction(request, signal),
+    mutation: { onSuccess: () => invalidateAll(queryClient) },
+  });
+  const cancel = useAllocationAction<{ ok: true }>({
+    submit: (request, signal) => backend.submitAllocationAction(request, signal),
+    mutation: { onSuccess: () => invalidateAll(queryClient) },
+  });
+
+  const [usdAmount, setUsdAmount] = useState('100.00');
+  const [bondAmount, setBondAmount] = useState('5.00');
+  const busy = createTrade.isPending || settle.isPending || requestAction.isPending || cancel.isPending;
+
+  return (
+    <Card title="Trades" hint="useAllocationRequests + useTokenAllocations + useChoice + request/allocation actions">
+      <div className="form-grid">
+        <Field label="USD amount (Alice pays)">
+          <input inputMode="decimal" value={usdAmount} onChange={(e) => setUsdAmount(e.target.value)} />
+        </Field>
+        <Field label="BOND amount (Bob delivers)">
+          <input inputMode="decimal" value={bondAmount} onChange={(e) => setBondAmount(e.target.value)} />
+        </Field>
+        <div className="field field-action">
+          <button
+            className="btn btn-primary"
+            disabled={busy || !isPositiveAmount(usdAmount) || !isPositiveAmount(bondAmount)}
+            onClick={() => createTrade.exerciseChoice({ usdAmount, bondAmount })}
+          >
+            New trade
+          </button>
+        </div>
+      </div>
+
+      <AsyncView
+        isPending={trades.isPending}
+        error={trades.error}
+        data={trades.requests}
+        isEmpty={(items) => items.length === 0}
+        empty="No open trades."
+      >
+        {(items) => (
+          <ul className="list">
+            {items.map((trade) => {
+              const legIds = Object.keys(trade.request.transferLegs);
+              const matched = matchedLegIds(trade.request, combined);
+              const allMatched = matched.length === legIds.length;
+              return (
+                <li key={trade.cid} className="row row-block">
+                  <div className="row-main">
+                    <div className="row-title">
+                      Trade {trade.request.settlement.settlementRef.id}{' '}
+                      <Badge tone={allMatched ? 'ok' : 'neutral'}>
+                        {matched.length}/{legIds.length} allocated
+                      </Badge>
+                    </div>
+                    {legIds.map((legId) => {
+                      const leg = trade.request.transferLegs[legId];
+                      const alloc = allocationForLeg(trade.request, legId, combined);
+                      return (
+                        <div key={legId} className="row-sub muted leg-status">
+                          <span>
+                            {legId}: {formatAmount(leg.amount)} {leg.instrumentId.id}{' '}
+                            {alloc ? <Badge tone="ok">matched</Badge> : <Badge tone="lock">missing</Badge>}
+                          </span>
+                          {alloc ? (
+                            <button
+                              className="btn btn-ghost btn-small"
+                              disabled={busy}
+                              onClick={() => cancel.submitAction({ allocationCid: alloc.cid, action: 'cancel' })}
+                            >
+                              Cancel allocation
+                            </button>
+                          ) : null}
+                        </div>
+                      );
+                    })}
+                  </div>
+                  <div className="row-actions">
+                    <button
+                      className="btn btn-primary btn-small"
+                      disabled={busy || !allMatched}
+                      title={allMatched ? 'Settle atomically' : 'All legs must be allocated first'}
+                      onClick={() => settle.exerciseChoice({ requestCid: trade.cid })}
+                    >
+                      Settle
+                    </button>
+                    <button
+                      className="btn btn-ghost btn-small"
+                      disabled={busy}
+                      onClick={() => requestAction.submitAction({ requestCid: trade.cid, action: 'withdraw' })}
+                    >
+                      Withdraw trade
+                    </button>
+                  </div>
+                </li>
+              );
+            })}
+          </ul>
+        )}
+      </AsyncView>
+
+      <TransactionToast status={toastStatus(createTrade)} error={createTrade.error} message={createTrade.isSuccess ? 'Trade created.' : undefined} />
+      <TransactionToast status={toastStatus(settle)} error={settle.error} message={settle.isSuccess ? 'Settled atomically. Balances swapped.' : undefined} />
+      <TransactionToast status={toastStatus(requestAction)} error={requestAction.error} message={requestAction.isSuccess ? 'Trade withdrawn.' : undefined} />
+      <TransactionToast status={toastStatus(cancel)} error={cancel.error} message={cancel.isSuccess ? 'Allocation cancelled.' : undefined} />
+    </Card>
+  );
+}

package/templates/react-dvp/src/ui/primitives.tsx

@@ -0,0 +1,91 @@
+/**
+ * Small presentational helpers for the demo chrome. These are the APP's own UI
+ * (cards, skeletons, badges, states), distinct from the themed PartyLayer
+ * primitives (ConnectButton, PartyAvatar, CostPreview, TransactionToast) which the
+ * sections import from `@partylayer/react`.
+ */
+import type { ReactNode } from 'react';
+
+export function Card({ title, hint, children }: { title: string; hint?: string; children: ReactNode }) {
+  return (
+    <section className="card">
+      <header className="card-head">
+        <h2>{title}</h2>
+        {hint ? <span className="card-hint">{hint}</span> : null}
+      </header>
+      <div className="card-body">{children}</div>
+    </section>
+  );
+}
+
+export function Skeleton({ rows = 3 }: { rows?: number }) {
+  return (
+    <div className="skeleton" aria-hidden="true">
+      {Array.from({ length: rows }).map((_, i) => (
+        <div key={i} className="skeleton-row" />
+      ))}
+    </div>
+  );
+}
+
+export function ErrorState({ error }: { error: Error }) {
+  return (
+    <div className="state state-error" role="alert">
+      <strong>Something went wrong.</strong>
+      <span>{error.message}</span>
+    </div>
+  );
+}
+
+export function EmptyState({ children }: { children: ReactNode }) {
+  return <div className="state state-empty">{children}</div>;
+}
+
+export function Badge({
+  tone = 'neutral',
+  title,
+  children,
+}: {
+  tone?: 'neutral' | 'lock' | 'ok';
+  title?: string;
+  children: ReactNode;
+}) {
+  return (
+    <span className={'badge badge-' + tone} title={title}>
+      {children}
+    </span>
+  );
+}
+
+export function Field({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <label className="field">
+      <span className="field-label">{label}</span>
+      {children}
+    </label>
+  );
+}
+
+/** A view of the standard read-hook state: pick loading, error, empty, or content. */
+export function AsyncView<T>({
+  isPending,
+  error,
+  data,
+  isEmpty,
+  empty,
+  children,
+  rows,
+}: {
+  isPending: boolean;
+  error: Error | null;
+  data: T | null | undefined;
+  isEmpty: (data: T) => boolean;
+  empty: ReactNode;
+  children: (data: T) => ReactNode;
+  rows?: number;
+}) {
+  if (isPending) return <Skeleton rows={rows} />;
+  if (error) return <ErrorState error={error} />;
+  if (data == null || isEmpty(data)) return <EmptyState>{empty}</EmptyState>;
+  return <>{children(data)}</>;
+}

package/templates/react-dvp/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/templates/react-dvp/vite.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+// https://vite.dev/config/
+export default defineConfig({
+  plugins: [react()],
+});

package/templates/react-tokenization/README.md

@@ -0,0 +1,139 @@
+# {{PROJECT_NAME}}
+
+A Tokenization vertical for Canton, scaffolded with create-partylayer-app. A
+single-page dApp that composes the full CIP-0056 (Canton Token Standard) helper
+surface from `@partylayer/react`, the UI primitives, and the theme families against
+a typed demo backend.
+
+Everything runs on an in-memory demo backend (typed fixtures behind a small
+`TokenizationBackend` interface), so every hook is exercised for real (loading,
+success, error, invalidation) without a live ledger. Model 2 throughout: PartyLayer
+owns none of the transport; the dApp supplies every read and submit fetcher, and the
+hooks type the request and wrap the query or mutation.
+
+> Reference quality, NOT production audited. This template demonstrates the API in a
+> realistic composition. Review, test, and harden it before using it in production.
+
+## Run it
+
+```bash
+npm create partylayer-app@latest my-app -- --template react-tokenization
+cd my-app
+npm install
+npm run dev
+```
+
+## What is on screen
+
+A header with the connect UI, a demo-party switcher (issuer / alice / bob), a
+synchronizer picker, and a light/dark toggle; then five section cards:
+
+| Section | Hook(s) exercised |
+| :-- | :-- |
+| Holdings | `useTokenHoldings` |
+| Transfer | `useTransferInstruction` (plus `CostPreview` and `TransactionToast`) |
+| Incoming | `useTransferInstructions` and `useTransferInstructionAction` |
+| Issuer | `useDamlContract` (instrument, supply, refs) and `useChoice` (mint, freeze) |
+| Allocations | `useTokenAllocations`, `useAllocationInstruction`, `useAllocationAction` |
+
+All seven CIP-0056 hooks are mounted and exercised, plus the two generic hooks
+(`useDamlContract`, `useChoice`) for the instrument reads and registry-specific
+writes the typed hooks do not cover.
+
+## Demo flows
+
+1. Connect. Click Connect Wallet in the header. The console adapter is registered, so
+   the wallet modal renders themed by the teal family. The sections below are driven
+   by the demo-party switcher, not the connection.
+2. View holdings with a frozen lock. As Alice, the Holdings card shows two holdings;
+   one carries a lock and renders a "Locked: frozen by issuer" badge.
+3. Transfer with a cost preview and a toast. In Transfer, pick a receiver and an
+   amount. A `CostPreview` shows the fee before you confirm; confirming drives a
+   `TransactionToast` from pending to success. The transfer initiates a pending
+   instruction and debits the sender; both sides refresh after invalidation.
+4. Accept the incoming transfer. Switch the demo party to the receiver (Bob). The
+   Incoming card shows the pending transfer. Accept and Reject render only while the
+   instruction is in the `pendingReceiverAcceptance` state (spec-accurate: those
+   choices are unavailable in the internal-workflow state, which instead shows the
+   `pendingActions` signal). Accept completes it and credits the receiver, and the
+   pending item disappears.
+5. Issuer mints. Switch to Issuer, enter a party and an amount under Mint. The total
+   supply and the target party's holdings update.
+6. Issuer freezes. As Issuer, pick a target party and toggle Freeze or Unfreeze on a
+   holding; the lock badge appears and the holding becomes unspendable in transfers.
+7. Error path. As any party, try to transfer more than the unlocked balance. The
+   submit rejects and the toast renders the error message.
+
+## Party-scoped caching
+
+Every hook call folds the current demo party into its `key` (for example
+`key: ['tokenization', 'holdings', party]`), so each party's data is cached
+independently. Switching parties never shows another party's cached data: a party you
+have not loaded shows a loading skeleton, and a party you have loaded shows its own
+data.
+
+Note on invalidation: the hooks nest your `key` inside their own key factory, so the
+real TanStack query key is `partyLayerKeys.tokenHoldings({ key })`, not the raw `key`
+you passed. To invalidate after a write, import `partyLayerKeys` from
+`@partylayer/react/query` and match on the factory (see `src/lib/invalidate.ts`).
+
+## Decimal handling
+
+Amounts are decimal strings end to end (never JS numbers), matching the CIP-0056
+`Decimal` convention. The demo store simplifies arithmetic to two decimal places
+using bigint cents (`src/lib/format.ts`); a real dApp handling arbitrary precision
+should use a decimal library instead of this two-place shortcut.
+
+## Real mode
+
+To wire this against a live validator and registry, replace the demo backend's
+fetchers. The hooks and the UI stay exactly as they are; only the fetchers change.
+
+Reads (holdings, instructions, allocations). Query your validator's active-contracts
+(ACS) endpoint with an interface filter and map each contract into the typed
+`{ cid, view }` ref the read hook returns (the `cid` is the ACS contract id, needed
+for the write requests):
+
+- holdings: interface filter `Splice.Api.Token.HoldingV1:Holding`, map into
+  `TokenHoldingRef` (`{ cid, holding }`); the `cid` feeds `inputHoldingCids`;
+- instructions: interface filter
+  `Splice.Api.Token.TransferInstructionV1:TransferInstruction`, map into
+  `TokenTransferInstructionRef` (`{ cid, instruction }`); the `cid` feeds
+  `TransferInstructionActionRequest.instructionCid`. Discriminate
+  `instruction.status.kind`: only `pendingReceiverAcceptance` allows Accept and
+  Reject; `pendingInternalWorkflow` carries `pendingActions` (which party could act
+  to advance the transfer);
+- allocations: interface filter `Splice.Api.Token.AllocationV1:Allocation`, map into
+  `TokenAllocationRef` (`{ cid, allocation }`); the `cid` feeds
+  `AllocationActionRequest.allocationCid`.
+
+Transfer initiation (`useTransferInstruction`). The registry flow is off-ledger and
+not standardized, so it lives in your `submit` fetcher: gather the sender's
+`inputHoldingCids`, POST the registry's transfer-instruction transfer-factory
+endpoint to get the `factoryId`, `choiceContext`, and `disclosedContracts`, fill
+`extraArgs.context`, then exercise `TransferFactory_Transfer` on the factory with the
+`disclosedContracts`.
+
+Transfer completion (`useTransferInstructionAction`). For accept, reject, or
+withdraw, fetch the per-action choice context from the registry, fill `extraArgs`,
+and exercise the choice on the instruction contract id with the `disclosedContracts`.
+
+Allocation create and act (`useAllocationInstruction`, `useAllocationAction`). Mirror
+the transfer flow against the registry's allocation-instruction factory endpoint and
+the per-action choice contexts for `Allocation_ExecuteTransfer`, `Allocation_Cancel`,
+and `Allocation_Withdraw`.
+
+For the shapes these fetchers pass around, `@partylayer/react/query` exports the
+disclosed contract and choice context types (`TokenDisclosedContract`,
+`TokenChoiceContext`, `TokenTransferFactory`, `TokenAllocationFactory`) plus
+`mergeDisclosedContracts` for combining the disclosures of several registry contexts
+into one submission.
+
+Issuer writes (mint, freeze). These are registry-specific admin operations, shown
+here through the generic `useChoice` escape hatch. Real registries typically expose
+issuance through the standard's `BurnMintV1` (`BurnMintFactory_BurnMint`, which
+returns `outputCids`) or a custom admin choice; the exact choice fields are
+registry-defined.
+
+The official Splice token-standard CLI is the canonical reference for these registry
+flows.

package/templates/react-tokenization/_gitignore

@@ -0,0 +1,8 @@
+node_modules
+dist
+dist-ssr
+*.local
+.DS_Store
+.env
+.env.*
+!.env.example

package/templates/react-tokenization/_package.json

@@ -0,0 +1,26 @@
+{
+  "name": "{{PROJECT_NAME}}",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@partylayer/react": "^2.2.1",
+    "@partylayer/sdk": "^0.16.0",
+    "@partylayer/adapter-console": "^0.3.15",
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "@vitejs/plugin-react": "^4.3.1",
+    "typescript": "^5.6.2",
+    "vite": "^5.4.2"
+  }
+}

package/templates/react-tokenization/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{PROJECT_NAME}}</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>