create-partylayer-app 0.4.0 → 0.5.0

package/templates/react-tokenization/src/sections/Holdings.tsx

@@ -0,0 +1,51 @@
+/**
+ * Holdings section. Exercises useTokenHoldings (CIP-0056 typed read). Renders each
+ * holding with the owner avatar, the amount (string precision preserved), the
+ * instrument, and a lock badge when the holding carries a TokenLock.
+ */
+import { useTokenHoldings } from '@partylayer/react/query';
+import { PartyAvatar } from '@partylayer/react';
+import { useDemo, partyKey } from '../context/DemoContext';
+import { Card, AsyncView, Badge } from '../ui/primitives';
+import { formatAmount } from '../lib/format';
+
+export function Holdings() {
+  const { party, backend } = useDemo();
+  const q = useTokenHoldings({
+    read: (signal) => backend.readHoldings(party, signal),
+    key: partyKey('holdings', party),
+  });
+
+  return (
+    <Card title="Holdings" hint="useTokenHoldings">
+      <AsyncView
+        isPending={q.isPending}
+        error={q.error}
+        data={q.holdings}
+        isEmpty={(refs) => refs.length === 0}
+        empty="No holdings yet for this party."
+      >
+        {(refs) => (
+          <ul className="list">
+            {refs.map(({ cid, holding: h }) => (
+              <li key={cid} className="row">
+                <PartyAvatar id={h.owner} size={28} />
+                <div className="row-main">
+                  <div className="row-title">
+                    {formatAmount(h.amount)} <span className="muted">{h.instrumentId.id}</span>
+                  </div>
+                  <div className="row-sub muted">admin {h.instrumentId.admin}</div>
+                </div>
+                {h.lock ? (
+                  <Badge tone="lock" title={'expires ' + (h.lock.expiresAt ?? 'never')}>
+                    Locked: {h.lock.context ?? 'held'}
+                  </Badge>
+                ) : null}
+              </li>
+            ))}
+          </ul>
+        )}
+      </AsyncView>
+    </Card>
+  );
+}

package/templates/react-tokenization/src/sections/Incoming.tsx

@@ -0,0 +1,107 @@
+/**
+ * Incoming section. Reads the current party's pending transfer instructions with
+ * the typed useTransferInstructions hook, and completes them with
+ * useTransferInstructionAction (accept / reject). Accept and Reject render ONLY
+ * when the instruction is in the pendingReceiverAcceptance state, matching the
+ * spec (those choices are unavailable in the internal-workflow state). On success
+ * it invalidates holdings and instructions so both sides refresh.
+ */
+import { useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { useTransferInstructions, useTransferInstructionAction } from '@partylayer/react/query';
+import { PartyAvatar, TransactionToast } from '@partylayer/react';
+import { useDemo, partyKey } from '../context/DemoContext';
+import { Card, AsyncView } from '../ui/primitives';
+import { toastStatus } from '../lib/mutation';
+import { invalidateHoldingsAndReads } from '../lib/invalidate';
+import { formatAmount } from '../lib/format';
+
+export function Incoming() {
+  const { party, backend } = useDemo();
+  const queryClient = useQueryClient();
+  const [actingCid, setActingCid] = useState<string | null>(null);
+
+  const q = useTransferInstructions({
+    read: (signal) => backend.readIncoming(party, signal),
+    key: partyKey('incoming', party),
+  });
+
+  const action = useTransferInstructionAction<{ ok: true }>({
+    submit: (request, signal) => backend.submitTransferAction(request, signal),
+    mutation: {
+      onSuccess: () => invalidateHoldingsAndReads(queryClient),
+    },
+  });
+
+  const act = (instructionCid: string, kind: 'accept' | 'reject') => {
+    setActingCid(instructionCid);
+    action.submitAction({ instructionCid, action: kind });
+  };
+
+  return (
+    <Card title="Incoming" hint="useTransferInstructions + useTransferInstructionAction">
+      <AsyncView
+        isPending={q.isPending}
+        error={q.error}
+        data={q.instructions}
+        isEmpty={(items) => items.length === 0}
+        empty="No pending incoming transfers."
+      >
+        {(items) => (
+          <ul className="list">
+            {items.map(({ cid, instruction }) => {
+              const t = instruction.transfer;
+              const acceptable = instruction.status.kind === 'pendingReceiverAcceptance';
+              return (
+                <li key={cid} className="row">
+                  <PartyAvatar id={t.sender} size={28} />
+                  <div className="row-main">
+                    <div className="row-title">
+                      {formatAmount(t.amount)} <span className="muted">{t.instrumentId.id}</span>
+                    </div>
+                    <div className="row-sub muted">
+                      from {t.sender} · execute before {t.executeBefore.slice(0, 10)}
+                      {t.meta?.memo ? ' · ' + t.meta.memo : ''}
+                    </div>
+                    {!acceptable ? (
+                      <div className="row-sub muted">
+                        pending internal workflow
+                        {instruction.status.kind === 'pendingInternalWorkflow'
+                          ? ' · waiting on ' + Object.keys(instruction.status.pendingActions).join(', ')
+                          : ''}
+                      </div>
+                    ) : null}
+                  </div>
+                  {acceptable ? (
+                    <div className="row-actions">
+                      <button
+                        className="btn btn-primary"
+                        disabled={action.isPending}
+                        onClick={() => act(cid, 'accept')}
+                      >
+                        Accept
+                      </button>
+                      <button
+                        className="btn btn-ghost"
+                        disabled={action.isPending}
+                        onClick={() => act(cid, 'reject')}
+                      >
+                        Reject
+                      </button>
+                    </div>
+                  ) : null}
+                </li>
+              );
+            })}
+          </ul>
+        )}
+      </AsyncView>
+
+      <TransactionToast
+        status={toastStatus(action)}
+        error={action.error}
+        message={action.isSuccess ? 'Instruction ' + (actingCid ?? '') + ' completed.' : undefined}
+      />
+    </Card>
+  );
+}

package/templates/react-tokenization/src/sections/Issuer.tsx

@@ -0,0 +1,177 @@
+/**
+ * Issuer section. Visible for every party; actionable only as the issuer (a hint
+ * shows otherwise). Reads the instrument config and total supply through the
+ * generic useDamlContract, and performs registry-specific admin writes (mint,
+ * freeze/unfreeze) through the generic useChoice: the escape hatch for writes the
+ * typed CIP-0056 hooks do not cover.
+ */
+import { useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { useDamlContract, useChoice, type TokenHoldingRef } from '@partylayer/react/query';
+import { TransactionToast } from '@partylayer/react';
+import { useDemo, partyKey } from '../context/DemoContext';
+import { Card, AsyncView, Badge, Field } from '../ui/primitives';
+import { toastStatus } from '../lib/mutation';
+import { invalidateHoldingsAndReads } from '../lib/invalidate';
+import { formatAmount, isPositiveAmount } from '../lib/format';
+import { PARTIES, PARTY_ORDER } from '../lib/fixtures';
+import type { IssuerChoice } from '../lib/backend';
+import type { DemoPartyKey, InstrumentConfig } from '../lib/types';
+
+export function Issuer() {
+  const { party, backend } = useDemo();
+  const queryClient = useQueryClient();
+  const isIssuer = party === 'issuer';
+
+  const instrument = useDamlContract<InstrumentConfig>({
+    read: (signal) => backend.readInstrument(signal),
+    key: ['tokenization', 'instrument'],
+  });
+  const supply = useDamlContract<string>({
+    read: (signal) => backend.readSupply(signal),
+    key: ['tokenization', 'supply'],
+  });
+
+  const [mintTarget, setMintTarget] = useState<DemoPartyKey>('alice');
+  const [mintAmount, setMintAmount] = useState('');
+  const [freezeTarget, setFreezeTarget] = useState<DemoPartyKey>('alice');
+
+  const refreshAll = () => invalidateHoldingsAndReads(queryClient);
+
+  const issuerChoice = useChoice<{ ok: true }, IssuerChoice>({
+    exercise: (choice) => backend.submitIssuerChoice(choice),
+    mutation: { onSuccess: refreshAll },
+  });
+
+  const freezeRefs = useDamlContract<TokenHoldingRef[]>({
+    read: (signal) => backend.readHoldingRefs(freezeTarget, signal),
+    key: partyKey('holdingRefs', freezeTarget),
+  });
+
+  const doMint = () => {
+    if (!isPositiveAmount(mintAmount)) return;
+    issuerChoice.exerciseChoice({ kind: 'mint', toParty: mintTarget, amount: mintAmount });
+    setMintAmount('');
+  };
+
+  const toggleFreeze = (ref: TokenHoldingRef) => {
+    issuerChoice.exerciseChoice({
+      kind: 'setFrozen',
+      party: freezeTarget,
+      cid: ref.cid,
+      frozen: !ref.holding.lock,
+    });
+  };
+
+  return (
+    <Card title="Issuer" hint="useDamlContract + useChoice">
+      <div className="issuer-summary">
+        <AsyncView
+          isPending={instrument.isPending}
+          error={instrument.error}
+          data={instrument.contract}
+          isEmpty={() => false}
+          empty=""
+          rows={2}
+        >
+          {(cfg) => (
+            <div>
+              <div className="row-title">
+                {cfg.name} <span className="muted">{cfg.id}</span>
+              </div>
+              <div className="row-sub muted">{cfg.description}</div>
+              <div className="row-sub muted">admin {cfg.admin}</div>
+            </div>
+          )}
+        </AsyncView>
+        <div className="supply">
+          <span className="muted">Total supply</span>
+          <strong>{supply.isPending ? '...' : formatAmount(supply.contract ?? '0.00')}</strong>
+        </div>
+      </div>
+
+      {!isIssuer ? (
+        <div className="state state-empty">
+          Switch the demo party to <strong>Issuer</strong> to mint and freeze.
+        </div>
+      ) : (
+        <>
+          <div className="form-grid">
+            <Field label="Mint to">
+              <select value={mintTarget} onChange={(e) => setMintTarget(e.target.value as DemoPartyKey)}>
+                {PARTY_ORDER.map((p) => (
+                  <option key={p} value={p}>
+                    {PARTIES[p].label}
+                  </option>
+                ))}
+              </select>
+            </Field>
+            <Field label="Amount">
+              <input
+                inputMode="decimal"
+                placeholder="0.00"
+                value={mintAmount}
+                onChange={(e) => setMintAmount(e.target.value)}
+              />
+            </Field>
+            <div className="field field-action">
+              <button className="btn btn-primary" onClick={doMint} disabled={issuerChoice.isPending}>
+                Mint
+              </button>
+            </div>
+          </div>
+
+          <div className="freeze">
+            <Field label="Freeze holdings of">
+              <select value={freezeTarget} onChange={(e) => setFreezeTarget(e.target.value as DemoPartyKey)}>
+                {PARTY_ORDER.map((p) => (
+                  <option key={p} value={p}>
+                    {PARTIES[p].label}
+                  </option>
+                ))}
+              </select>
+            </Field>
+            <AsyncView
+              isPending={freezeRefs.isPending}
+              error={freezeRefs.error}
+              data={freezeRefs.contract}
+              isEmpty={(refs) => refs.length === 0}
+              empty="No holdings to freeze."
+              rows={2}
+            >
+              {(refs) => (
+                <ul className="list">
+                  {refs.map((ref) => (
+                    <li key={ref.cid} className="row">
+                      <div className="row-main">
+                        <div className="row-title">
+                          {formatAmount(ref.holding.amount)}{' '}
+                          <span className="muted">{ref.holding.instrumentId.id}</span>
+                        </div>
+                        <div className="row-sub muted">{ref.cid}</div>
+                      </div>
+                      {ref.holding.lock ? <Badge tone="lock">Frozen</Badge> : null}
+                      <button
+                        className="btn btn-ghost"
+                        disabled={issuerChoice.isPending}
+                        onClick={() => toggleFreeze(ref)}
+                      >
+                        {ref.holding.lock ? 'Unfreeze' : 'Freeze'}
+                      </button>
+                    </li>
+                  ))}
+                </ul>
+              )}
+            </AsyncView>
+          </div>
+
+          <TransactionToast
+            status={toastStatus(issuerChoice)}
+            error={issuerChoice.error}
+            message={issuerChoice.isSuccess ? 'Issuer action applied.' : undefined}
+          />
+        </>
+      )}
+    </Card>
+  );
+}

package/templates/react-tokenization/src/sections/Transfer.tsx

@@ -0,0 +1,112 @@
+/**
+ * Transfer section. Builds a standard TokenTransfer and submits it through
+ * useTransferInstruction. Shows CostPreview before confirm and drives a
+ * TransactionToast from the mutation state. On success it invalidates the holdings
+ * and incoming query keys so both sides refresh.
+ */
+import { useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { useTransferInstruction, type TokenTransfer } from '@partylayer/react/query';
+import { CostPreview, TransactionToast } from '@partylayer/react';
+import { useDemo } from '../context/DemoContext';
+import { Card, Field } from '../ui/primitives';
+import { toastStatus } from '../lib/mutation';
+import { invalidateHoldingsAndReads } from '../lib/invalidate';
+import { PARTIES, PARTY_ORDER, INSTRUMENT, FEE_ESTIMATE } from '../lib/fixtures';
+import { demoStore } from '../lib/store';
+import { formatAmount, isPositiveAmount } from '../lib/format';
+import type { DemoPartyKey } from '../lib/types';
+
+export function Transfer() {
+  const { party, backend } = useDemo();
+  const queryClient = useQueryClient();
+
+  const others = PARTY_ORDER.filter((p) => p !== party);
+  const [receiver, setReceiver] = useState<DemoPartyKey>(others[0]);
+  const [amount, setAmount] = useState('');
+  const [memo, setMemo] = useState('');
+
+  const mutation = useTransferInstruction<{ ok: true }>({
+    submit: (transfer, signal) => backend.submitTransfer(transfer, signal),
+    mutation: {
+      onSuccess: () => {
+        // Refresh every party's holdings and incoming so both sides update.
+        invalidateHoldingsAndReads(queryClient);
+        setAmount('');
+        setMemo('');
+      },
+    },
+  });
+
+  // Keep the receiver valid when the acting party changes.
+  const receiverKey = others.includes(receiver) ? receiver : others[0];
+  const balance = demoStore.balanceOf(party);
+  const valid = isPositiveAmount(amount);
+
+  const onConfirm = () => {
+    const now = new Date();
+    const transfer: TokenTransfer = {
+      sender: PARTIES[party].partyId,
+      receiver: PARTIES[receiverKey].partyId,
+      amount,
+      instrumentId: { admin: INSTRUMENT.admin, id: INSTRUMENT.id },
+      requestedAt: now.toISOString(),
+      executeBefore: new Date(now.getTime() + 24 * 60 * 60 * 1000).toISOString(),
+      inputHoldingCids: demoStore.unlockedCids(party),
+      meta: memo ? { memo } : {},
+    };
+    mutation.submitTransfer(transfer);
+  };
+
+  return (
+    <Card title="Transfer" hint="useTransferInstruction">
+      <div className="muted balance-line">
+        Available to send: <strong>{formatAmount(balance)}</strong> {INSTRUMENT.id}
+      </div>
+
+      <div className="form-grid">
+        <Field label="Receiver">
+          <select value={receiverKey} onChange={(e) => setReceiver(e.target.value as DemoPartyKey)}>
+            {others.map((p) => (
+              <option key={p} value={p}>
+                {PARTIES[p].label}
+              </option>
+            ))}
+          </select>
+        </Field>
+        <Field label={'Amount (' + INSTRUMENT.id + ')'}>
+          <input
+            inputMode="decimal"
+            placeholder="0.00"
+            value={amount}
+            onChange={(e) => setAmount(e.target.value)}
+          />
+        </Field>
+        <Field label="Memo (optional)">
+          <input value={memo} placeholder="what is it for" onChange={(e) => setMemo(e.target.value)} />
+        </Field>
+      </div>
+
+      {valid ? (
+        <div className="review">
+          <div className="review-line">
+            Send <strong>{formatAmount(amount)}</strong> {INSTRUMENT.id} to{' '}
+            <strong>{PARTIES[receiverKey].label}</strong>
+          </div>
+          <CostPreview estimate={FEE_ESTIMATE} />
+          <button className="btn btn-primary" onClick={onConfirm} disabled={mutation.isPending}>
+            {mutation.isPending ? 'Submitting...' : 'Confirm transfer'}
+          </button>
+        </div>
+      ) : (
+        <div className="muted hint-line">Enter a positive amount to preview the fee and confirm.</div>
+      )}
+
+      <TransactionToast
+        status={toastStatus(mutation)}
+        error={mutation.error}
+        message={mutation.isSuccess ? 'Transfer sent. The receiver can now accept it.' : undefined}
+      />
+    </Card>
+  );
+}

package/templates/react-tokenization/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-tokenization/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-tokenization/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-vite/_package.json

@@ -9,8 +9,9 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@partylayer/react": "^0.9.1",
-    "@partylayer/sdk": "^0.10.0",
+    "@partylayer/react": "^2.1.0",
+    "@partylayer/sdk": "^0.15.0",
+    "@tanstack/react-query": "^5.0.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   },

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

@@ -12,7 +12,7 @@ export default function App() {
     <PartyLayerKit network="devnet" appName="{{PROJECT_NAME}}">
       <main className="app">
         <h1>{{PROJECT_NAME}}</h1>
-        <p className="subtitle">A PartyLayer dApp on Canton — connect any verified wallet.</p>
+        <p className="subtitle">A PartyLayer dApp on Canton: connect any verified wallet.</p>
         <ConnectButton />
         <SessionPanel />
       </main>

package/templates/react-vite/src/main.tsx

@@ -1,10 +1,20 @@
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
 import App from './App';
 import './index.css';
 
+// PartyLayer's data hooks (the `@partylayer/react/query` entrypoint:
+// useDamlContract, useChoice, the cost hooks) are built on TanStack Query, so
+// they need a QueryClient in context. Create one here and wrap the app. The base
+// session surface (PartyLayerKit, ConnectButton, useAccount) works without it,
+// but having it set up means the query hooks are ready when you reach for them.
+const queryClient = new QueryClient();
+
 createRoot(document.getElementById('root')!).render(
   <StrictMode>
-    <App />
+    <QueryClientProvider client={queryClient}>
+      <App />
+    </QueryClientProvider>
   </StrictMode>,
 );

package/templates/vanilla/_package.json

@@ -9,7 +9,7 @@
     "preview": "vite preview"
   },
   "dependencies": {
-    "@partylayer/sdk": "^0.10.0"
+    "@partylayer/sdk": "^0.15.0"
   },
   "devDependencies": {
     "typescript": "^5.6.2",

package/templates/vue-nuxt-pinia/_package.json

@@ -10,10 +10,11 @@
     "postinstall": "nuxt prepare"
   },
   "dependencies": {
-    "@partylayer/sdk": "^0.10.0",
-    "@partylayer/session": "^1.1.0",
-    "@partylayer/vue": "^0.1.3",
+    "@partylayer/sdk": "^0.15.0",
+    "@partylayer/session": "^1.1.4",
+    "@partylayer/vue": "^1.0.1",
     "@pinia/nuxt": "^0.5.5",
+    "@tanstack/vue-query": "^5.0.0",
     "pinia": "^2.2.0",
     "vue": "^3.5.0"
   },

package/templates/vue-nuxt-pinia/app.vue

@@ -15,14 +15,14 @@ const sessionStore = useSessionStore();
 <template>
   <main class="app">
     <h1>{{PROJECT_NAME}}</h1>
-    <p class="subtitle">A PartyLayer dApp on Canton — Nuxt 3 + Pinia, SSR session.</p>
+    <p class="subtitle">A PartyLayer dApp on Canton: Nuxt 3 + Pinia, SSR session.</p>
 
     <!-- SERVER-RENDERED party from the cookie (initial HTML, no flash) -->
     <p v-if="serverParty" class="session">
       Connected as <code data-testid="server-party">{{ truncateParty(serverParty) }}</code>
     </p>
     <p v-else class="session" data-testid="server-cta">
-      Not connected — connect a wallet to continue.
+      Not connected: connect a wallet to continue.
     </p>
 
     <!-- Pinia-backed interactive session (reads the Pinia store, not the composables) -->