create-partylayer-app 0.4.1 → 0.5.1

package/templates/react-dvp/src/App.tsx

@@ -0,0 +1,110 @@
+/**
+ * The DvP vertical example shell.
+ *
+ * PartyLayerKit provides the session + theme context (mirroring the react-vite
+ * template's setup), themed with the `gold` family and a light/dark toggle. The
+ * header carries the connect UI and a DEMO-PARTY switcher: switching the demo party
+ * changes whose data every section reads and who acts (venue vs counterparty). It
+ * is app state, separate from the wallet session.
+ */
+import { useState } from 'react';
+import {
+  PartyLayerKit,
+  ConnectButton,
+  SynchronizerSwitcher,
+  themes,
+  type SynchronizerOption,
+} from '@partylayer/react';
+import { ConsoleAdapter } from '@partylayer/adapter-console';
+import { DemoProvider } from './context/DemoContext';
+import { demoBackend } from './lib/backend';
+import { PARTIES, PARTY_ORDER } from './lib/fixtures';
+import type { DemoPartyKey } from './lib/types';
+import { Trades } from './sections/Trades';
+import { MyAllocations } from './sections/MyAllocations';
+import { Holdings } from './sections/Holdings';
+import './App.css';
+
+// The dev wallet adapter apps/demo uses, so the connect surface works in a demo
+// context. The demo-party switcher, not this connection, drives the section data.
+const ADAPTERS = [new ConsoleAdapter()];
+
+const SYNCHRONIZERS: SynchronizerOption[] = [
+  { networkId: 'canton:da-devnet', label: 'DevNet' },
+  { networkId: 'canton:da-testnet', label: 'TestNet' },
+];
+
+export default function App() {
+  const [mode, setMode] = useState<'light' | 'dark'>('light');
+  const [party, setParty] = useState<DemoPartyKey>('venue');
+  const [synchronizer, setSynchronizer] = useState('canton:da-devnet');
+
+  const theme = mode === 'dark' ? themes.gold.dark : themes.gold.light;
+
+  return (
+    <PartyLayerKit network="devnet" appName="PartyLayer DvP" theme={theme} adapters={ADAPTERS}>
+      <DemoProvider value={{ party, setParty, backend: demoBackend, mode }}>
+        <div className={'app app-' + mode}>
+          <header className="topbar">
+            <div className="brand">
+              <span className="brand-mark" aria-hidden="true" />
+              <div>
+                <div className="brand-title">DvP</div>
+                <div className="brand-sub">delivery versus payment, CIP-0056 allocations</div>
+              </div>
+            </div>
+
+            <div className="topbar-controls">
+              <div className="party-switch" role="group" aria-label="demo party">
+                <span className="party-switch-label">demo party</span>
+                {PARTY_ORDER.map((p) => (
+                  <button
+                    key={p}
+                    className={'party-chip' + (party === p ? ' party-chip-on' : '')}
+                    onClick={() => setParty(p)}
+                  >
+                    {PARTIES[p].label}
+                  </button>
+                ))}
+              </div>
+
+              <SynchronizerSwitcher
+                networkId={synchronizer}
+                options={SYNCHRONIZERS}
+                onSwitch={setSynchronizer}
+              />
+
+              <button
+                className="btn btn-ghost"
+                onClick={() => setMode((m) => (m === 'dark' ? 'light' : 'dark'))}
+              >
+                {mode === 'dark' ? 'Light' : 'Dark'}
+              </button>
+
+              <ConnectButton />
+            </div>
+          </header>
+
+          <p className="acting-line">
+            Acting as <strong>{PARTIES[party].label}</strong>{' '}
+            <code>{PARTIES[party].partyId}</code>.{' '}
+            {party === 'venue'
+              ? 'The venue creates trades and settles atomically once both legs are allocated.'
+              : 'Allocate your leg of a trade, or reject it.'}
+          </p>
+
+          <main className="grid">
+            <Trades />
+            <MyAllocations />
+            <Holdings />
+          </main>
+
+          <footer className="footer">
+            Demo backend, in-memory fixtures. Model 2: the dApp supplies every read and submit.
+            See the README for the atomic settle semantics and real-mode wiring.
+          </footer>
+        </div>
+      </DemoProvider>
+    </PartyLayerKit>
+  );
+}

package/templates/react-dvp/src/context/DemoContext.tsx

@@ -0,0 +1,34 @@
+import { createContext, useContext } from 'react';
+import type { DemoPartyKey } from '../lib/types';
+import type { DvpBackend } from '../lib/backend';
+
+/**
+ * The demo context threads the current demo party, the backend, and the theme mode
+ * to every section. The current party is app state (a demo-party switcher), SEPARATE
+ * from the wallet session: it selects whose data the sections read and who acts.
+ */
+export interface DemoContextValue {
+  party: DemoPartyKey;
+  setParty: (party: DemoPartyKey) => void;
+  backend: DvpBackend;
+  mode: 'light' | 'dark';
+}
+
+const DemoContext = createContext<DemoContextValue | null>(null);
+
+export const DemoProvider = DemoContext.Provider;
+
+export function useDemo(): DemoContextValue {
+  const ctx = useContext(DemoContext);
+  if (!ctx) throw new Error('useDemo must be used within a DemoProvider.');
+  return ctx;
+}
+
+/**
+ * Party-scoped query key. Every hook folds the current party into its cache key so
+ * switching parties never shows another party's cached data. The `scope` names the
+ * section (trades, allocations, holdings).
+ */
+export function partyKey(scope: string, party: DemoPartyKey): [string, string, DemoPartyKey] {
+  return ['dvp', scope, party];
+}

package/templates/react-dvp/src/index.css

@@ -0,0 +1,23 @@
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html,
+body,
+#root {
+  margin: 0;
+  padding: 0;
+  min-height: 100%;
+}
+
+body {
+  font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Inter, Roboto,
+    'Helvetica Neue', Arial, sans-serif;
+  line-height: 1.5;
+}
+
+button {
+  font-family: inherit;
+}

package/templates/react-dvp/src/lib/backend.ts

@@ -0,0 +1,144 @@
+/**
+ * The backend interface the hooks read/submit through, plus a demo implementation
+ * against the in-memory store. Model 2: PartyLayer owns none of this; the dApp
+ * supplies these fetchers. In real mode each method becomes an ACS query or a
+ * registry-mediated / trade-app command submission (see the README "Real mode").
+ */
+import type {
+  TokenHoldingRef,
+  TokenAllocationRef,
+  TokenAllocationRequestRef,
+  AllocationInstructionRequest,
+  AllocationActionRequest,
+  AllocationRequestActionRequest,
+} from '@partylayer/react/query';
+import type { DemoPartyKey, SettleTrade, CreateTrade } from './types';
+import { demoStore, latency } from './store';
+import { PARTIES } from './fixtures';
+
+export interface DvpBackend {
+  /** ACS read: a party's holdings as `{ cid, holding }` refs. `null` means none yet. */
+  readHoldings(party: DemoPartyKey, signal?: AbortSignal): Promise<TokenHoldingRef[] | null>;
+  /** ACS read: the open trades (allocation requests). `null` means none yet. */
+  readTrades(signal?: AbortSignal): Promise<TokenAllocationRequestRef[] | null>;
+  /** ACS read: a party's allocations as `{ cid, allocation }` refs. `null` means none yet. */
+  readAllocations(party: DemoPartyKey, signal?: AbortSignal): Promise<TokenAllocationRef[] | null>;
+  /** Which leg ids of a trade currently have a matching allocation (venue view). */
+  readMatchedLegs(requestCid: string, signal?: AbortSignal): Promise<string[]>;
+
+  /** Submit: allocate a leg (create an allocation via the factory). */
+  submitAllocation(request: AllocationInstructionRequest, signal?: AbortSignal): Promise<{ ok: true }>;
+  /** Submit: act on a funded allocation (withdraw / cancel). */
+  submitAllocationAction(request: AllocationActionRequest, signal?: AbortSignal): Promise<{ ok: true }>;
+  /** Submit: respond to a trade request (reject / withdraw). */
+  submitRequestAction(request: AllocationRequestActionRequest, signal?: AbortSignal): Promise<{ ok: true }>;
+  /** Submit: the venue's atomic settle (a trade-app choice, via the generic useChoice). */
+  submitSettle(vars: SettleTrade, signal?: AbortSignal): Promise<{ ok: true }>;
+  /** Submit: the venue creates a new trade (its own settlement-app choice). */
+  submitCreateTrade(vars: CreateTrade, signal?: AbortSignal): Promise<{ ok: true }>;
+}
+
+/** Reject if the caller aborted while we were "in flight". */
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) throw new DOMException('Aborted', 'AbortError');
+}
+
+function partyIdToKey(partyId: string): DemoPartyKey {
+  for (const key of Object.keys(PARTIES) as DemoPartyKey[]) {
+    if (PARTIES[key].partyId === partyId) return key;
+  }
+  throw new Error('Unknown party id: ' + partyId);
+}
+
+/** The allocation cid a party owns, matched by a request/leg an action targets. */
+function findAllocationParty(allocationCid: string): DemoPartyKey {
+  for (const key of Object.keys(PARTIES) as DemoPartyKey[]) {
+    if (demoStore.allocationsOf(key).some((a) => a.cid === allocationCid)) return key;
+  }
+  throw new Error('Allocation not found: ' + allocationCid);
+}
+
+export const demoBackend: DvpBackend = {
+  async readHoldings(party, signal) {
+    await latency();
+    throwIfAborted(signal);
+    return demoStore.holdingsOf(party);
+  },
+
+  async readTrades(signal) {
+    await latency();
+    throwIfAborted(signal);
+    return demoStore.requestsPending();
+  },
+
+  async readAllocations(party, signal) {
+    await latency();
+    throwIfAborted(signal);
+    return demoStore.allocationsOf(party);
+  },
+
+  async readMatchedLegs(requestCid, signal) {
+    await latency();
+    throwIfAborted(signal);
+    return demoStore.matchedLegIds(requestCid);
+  },
+
+  async submitAllocation(request, signal) {
+    await latency();
+    throwIfAborted(signal);
+    // The allocation spec was composed from the request; map it back to the store's
+    // requestCid + legId + sender. The sender selects backing holdings itself
+    // (inputHoldingCids), which the store consumes.
+    const requestCid = request.allocation.settlement.settlementRef.cid;
+    if (!requestCid) throw new Error('Allocation is missing its settlement request cid.');
+    const legId = request.allocation.transferLegId;
+    const sender = partyIdToKey(request.allocation.transferLeg.sender);
+    demoStore.allocate(sender, requestCid, legId, request.inputHoldingCids);
+    return { ok: true };
+  },
+
+  async submitAllocationAction(request, signal) {
+    await latency();
+    throwIfAborted(signal);
+    if (request.action === 'withdraw') {
+      const party = findAllocationParty(request.allocationCid);
+      demoStore.withdrawAllocation(party, request.allocationCid);
+    } else if (request.action === 'cancel') {
+      demoStore.cancelAllocation(request.allocationCid);
+    } else {
+      // executeTransfer is a per-allocation move; in this vertical the venue settles
+      // all legs atomically instead, so it is not wired here.
+      throw new Error('executeTransfer is settled atomically by the venue in this example.');
+    }
+    return { ok: true };
+  },
+
+  async submitRequestAction(request, signal) {
+    await latency();
+    throwIfAborted(signal);
+    if (request.action === 'reject') {
+      demoStore.rejectRequest(request.requestCid, request.actor);
+    } else {
+      demoStore.withdrawRequest(request.requestCid);
+    }
+    return { ok: true };
+  },
+
+  // The venue's settle is a dApp-specific trade choice, wired through the generic
+  // useChoice. A real venue settles atomically via its trade contract's choice whose
+  // body exercises Allocation_ExecuteTransfer per leg in a single transaction, which
+  // is exactly why this is useChoice and not the per-allocation typed hook.
+  async submitSettle(vars, signal) {
+    await latency();
+    throwIfAborted(signal);
+    demoStore.settle(vars.requestCid);
+    return { ok: true };
+  },
+
+  async submitCreateTrade(vars, signal) {
+    await latency();
+    throwIfAborted(signal);
+    demoStore.createTrade(vars.usdAmount, vars.bondAmount);
+    return { ok: true };
+  },
+};

package/templates/react-dvp/src/lib/fixtures.ts

@@ -0,0 +1,113 @@
+/**
+ * Typed seed data for the DvP demo backend, built from the REAL exported CIP-0056
+ * types. A settlement venue plus two counterparties, two registry-administered
+ * instruments (DEMO-USD, DEMO-BOND), seed holdings, and one open trade (an
+ * allocation request with two opposite legs).
+ */
+import { toTrafficCost, type CostEstimation } from '@partylayer/react';
+import type {
+  TokenHolding,
+  TokenHoldingRef,
+  TokenAllocationRequestRef,
+  TokenTransferLeg,
+} from '@partylayer/react/query';
+import type { DemoParty, DemoPartyKey, InstrumentConfig } from './types';
+
+/**
+ * The registry party that administers both instruments. NOT selectable as a demo
+ * party: the executor (venue) and the registry admin are distinct roles.
+ */
+export const REGISTRY = 'registry::1220c0ffee';
+
+export const PARTIES: Record<DemoPartyKey, DemoParty> = {
+  venue: { key: 'venue', label: 'Venue', partyId: 'venue::12208a3f9b' },
+  alice: { key: 'alice', label: 'Alice', partyId: 'alice::1220b7c142' },
+  bob: { key: 'bob', label: 'Bob', partyId: 'bob::1220e4d9a0' },
+};
+
+export const PARTY_ORDER: DemoPartyKey[] = ['venue', 'alice', 'bob'];
+
+export const USD: InstrumentConfig = { admin: REGISTRY, id: 'DEMO-USD', name: 'Demo USD' };
+export const BOND: InstrumentConfig = { admin: REGISTRY, id: 'DEMO-BOND', name: 'Demo Bond' };
+
+/** The two transfer-leg identifiers a trade settles across. */
+export const LEG_USD = 'leg-usd';
+export const LEG_BOND = 'leg-bond';
+
+/** Far-future ISO deadlines for the seed trade (stable, not time-based). */
+export const DEFAULT_ALLOCATE_BEFORE = '2027-01-01T00:00:00Z';
+export const DEFAULT_SETTLE_BEFORE = '2027-01-02T00:00:00Z';
+
+function holding(owner: string, admin: string, id: string, amount: string): TokenHolding {
+  return { owner, instrumentId: { admin, id }, amount, lock: undefined, meta: {} };
+}
+
+/** The seed holdings: Alice holds USD, Bob holds BOND, the venue holds nothing. */
+export function seedHoldings(): Record<DemoPartyKey, TokenHoldingRef[]> {
+  return {
+    venue: [],
+    alice: [
+      { cid: 'h-alice-usd-1', holding: holding(PARTIES.alice.partyId, USD.admin, USD.id, '300.00') },
+      { cid: 'h-alice-usd-2', holding: holding(PARTIES.alice.partyId, USD.admin, USD.id, '50.00') },
+    ],
+    bob: [{ cid: 'h-bob-bond-1', holding: holding(PARTIES.bob.partyId, BOND.admin, BOND.id, '10.00') }],
+  };
+}
+
+/**
+ * Build a trade as an allocation request: two opposite legs (Alice pays USD to Bob,
+ * Bob delivers BOND to Alice), an executor of the venue, and the given deadlines.
+ */
+export function buildTrade(
+  tradeId: string,
+  requestCid: string,
+  usdAmount: string,
+  bondAmount: string,
+  allocateBefore: string,
+  settleBefore: string,
+): TokenAllocationRequestRef {
+  const legUsd: TokenTransferLeg = {
+    sender: PARTIES.alice.partyId,
+    receiver: PARTIES.bob.partyId,
+    amount: usdAmount,
+    instrumentId: { admin: USD.admin, id: USD.id },
+  };
+  const legBond: TokenTransferLeg = {
+    sender: PARTIES.bob.partyId,
+    receiver: PARTIES.alice.partyId,
+    amount: bondAmount,
+    instrumentId: { admin: BOND.admin, id: BOND.id },
+  };
+  return {
+    cid: requestCid,
+    request: {
+      settlement: {
+        executor: PARTIES.venue.partyId,
+        settlementRef: { id: tradeId, cid: requestCid },
+        requestedAt: '2026-07-22T09:00:00Z',
+        allocateBefore,
+        settleBefore,
+        meta: { venue: 'demo' },
+      },
+      transferLegs: { [LEG_USD]: legUsd, [LEG_BOND]: legBond },
+      meta: { trade: tradeId },
+    },
+  };
+}
+
+/** The seed open trade: 100 USD against 5 BOND. */
+export function seedRequests(): TokenAllocationRequestRef[] {
+  return [buildTrade('trade-1', 'ar-cid-1', '100.00', '5.00', DEFAULT_ALLOCATE_BEFORE, DEFAULT_SETTLE_BEFORE)];
+}
+
+/**
+ * A fixed fee estimate for CostPreview before a leg allocation. The three fields are
+ * int64-as-string (`TrafficCost`); built with `toTrafficCost` re-exported from
+ * `@partylayer/react`, so no direct core dependency is needed.
+ */
+export const FEE_ESTIMATE: CostEstimation = {
+  estimationTimestamp: '2026-07-22T09:00:00Z',
+  confirmationRequestTrafficCostEstimation: toTrafficCost('1500'),
+  confirmationResponseTrafficCostEstimation: toTrafficCost('900'),
+  totalTrafficCostEstimation: toTrafficCost('2400'),
+};

package/templates/react-dvp/src/lib/format.ts

@@ -0,0 +1,59 @@
+/**
+ * Minimal fixed-point decimal helpers for the demo.
+ *
+ * Amounts are decimal strings END TO END (never JS numbers), matching the
+ * CIP-0056 `Decimal` convention where precision must survive. This demo SIMPLIFIES
+ * to two decimal places using bigint cents, which is enough for the two-decimal
+ * fixtures; a real dApp handling arbitrary-precision decimals should use a decimal
+ * library rather than this two-place shortcut. Documented in the README.
+ */
+const SCALE = 100n;
+
+/** Parse a two-decimal amount string into integer cents (bigint). */
+export function toCents(amount: string): bigint {
+  const trimmed = amount.trim();
+  const negative = trimmed.startsWith('-');
+  const body = negative ? trimmed.slice(1) : trimmed;
+  const [whole, frac = ''] = body.split('.');
+  const cents = BigInt(whole || '0') * SCALE + BigInt(((frac + '00').slice(0, 2)) || '0');
+  return negative ? -cents : cents;
+}
+
+/** Render integer cents back to a two-decimal amount string. */
+export function fromCents(cents: bigint): string {
+  const negative = cents < 0n;
+  const abs = negative ? -cents : cents;
+  const whole = abs / SCALE;
+  const frac = abs % SCALE;
+  const s = whole.toString() + '.' + frac.toString().padStart(2, '0');
+  return negative ? '-' + s : s;
+}
+
+export function addAmount(a: string, b: string): string {
+  return fromCents(toCents(a) + toCents(b));
+}
+
+export function subAmount(a: string, b: string): string {
+  return fromCents(toCents(a) - toCents(b));
+}
+
+/** Returns 1 / 0 / -1 for a > b / a === b / a < b. */
+export function cmpAmount(a: string, b: string): number {
+  const d = toCents(a) - toCents(b);
+  return d > 0n ? 1 : d < 0n ? -1 : 0;
+}
+
+/** Group the integer part with thousands separators; keep two decimals. */
+export function formatAmount(amount: string): string {
+  const [whole, frac = '00'] = amount.split('.');
+  const negative = whole.startsWith('-');
+  const digits = negative ? whole.slice(1) : whole;
+  const grouped = digits.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+  return (negative ? '-' : '') + grouped + '.' + frac.padEnd(2, '0').slice(0, 2);
+}
+
+/** Whether an amount is a valid non-negative two-decimal number greater than zero. */
+export function isPositiveAmount(amount: string): boolean {
+  if (!/^\d+(\.\d{1,2})?$/.test(amount.trim())) return false;
+  return toCents(amount) > 0n;
+}

package/templates/react-dvp/src/lib/invalidate.ts

@@ -0,0 +1,18 @@
+/**
+ * Cache invalidation helper.
+ *
+ * The CIP-0056 read hooks namespace the consumer's `key` under their own key
+ * factory, so the real TanStack queryKey is `partyLayerKeys.tokenHoldings({ key })`,
+ * NOT the raw `key`. Invalidation therefore goes through the exported
+ * `partyLayerKeys` factories (an empty-args call prefix-matches every party's
+ * entry), as the hooks' `key` JSDoc and the `partyLayerKeys` doc spell out.
+ */
+import type { QueryClient } from '@tanstack/react-query';
+import { partyLayerKeys } from '@partylayer/react/query';
+
+/** Refresh every party's trades, allocations, and holdings after a write. */
+export function invalidateAll(queryClient: QueryClient): void {
+  queryClient.invalidateQueries({ queryKey: partyLayerKeys.allocationRequests() });
+  queryClient.invalidateQueries({ queryKey: partyLayerKeys.tokenAllocations() });
+  queryClient.invalidateQueries({ queryKey: partyLayerKeys.tokenHoldings() });
+}

package/templates/react-dvp/src/lib/match.ts

@@ -0,0 +1,28 @@
+/**
+ * Thin app helpers over the canonical matching comparator now owned by
+ * `@partylayer/react`. The DvP finding that motivated the package helper is
+ * resolved; this file only adapts `allocationMatchesRequestLeg` to the array-search
+ * conveniences the venue view uses (find the allocation for a leg, list matched leg
+ * ids). No app-level amount comparator lives here anymore.
+ */
+import { allocationMatchesRequestLeg } from '@partylayer/react/query';
+import type { TokenAllocationRef, TokenAllocationRequest } from '@partylayer/react/query';
+
+/** The allocation ref that satisfies a request's leg, if any. */
+export function allocationForLeg(
+  request: TokenAllocationRequest,
+  legId: string,
+  allocations: TokenAllocationRef[],
+): TokenAllocationRef | undefined {
+  return allocations.find((a) => allocationMatchesRequestLeg(a.allocation, request, legId));
+}
+
+/** The leg ids of a request that are satisfied by the given allocations. */
+export function matchedLegIds(
+  request: TokenAllocationRequest,
+  allocations: TokenAllocationRef[],
+): string[] {
+  return Object.keys(request.transferLegs).filter(
+    (legId) => !!allocationForLeg(request, legId, allocations),
+  );
+}

package/templates/react-dvp/src/lib/mutation.ts

@@ -0,0 +1,17 @@
+import type { TransactionToastStatus } from '@partylayer/react';
+
+/**
+ * Map a TanStack mutation's flags to the `TransactionToast` status prop. This is
+ * the documented mapping the toast's JSDoc describes: pending, success, error, else
+ * idle. Presentational: the toast renders whatever status the dApp derives here.
+ */
+export function toastStatus(m: {
+  isPending: boolean;
+  isSuccess: boolean;
+  isError: boolean;
+}): TransactionToastStatus {
+  if (m.isPending) return 'pending';
+  if (m.isSuccess) return 'success';
+  if (m.isError) return 'error';
+  return 'idle';
+}