@capxul/sdk-react 4.20.0-beta.5 → 4.20.0-beta.6

package/README.md

@@ -56,6 +56,8 @@ export function Providers({ children }: { children: React.ReactNode }) {
   engine hook stays module-scoped. Both actor paths ship: a personal actor omits
   `.Source` and spends the personal Account; an organization actor holds the
   Budget the payment is drawn from and spends the treasury Account.
+  The submitted amount uses the selected registry AssetId and precision. This
+  includes 18-decimal WETH.
 - `CapxulContacts` is the compound address-book component. One root owns the
   book behaviour and draws nothing. The `.Summary`, `.List`, and `.Add` region
   parts each hand the screen one finished slice, and a `.List` row carries its
@@ -75,6 +77,9 @@ export function Providers({ children }: { children: React.ReactNode }) {
   and an amount the caller passed in `prefill` wins over it. Both engine hooks
   stay module-scoped.
 
+Activity groups use AssetId. The SDK resolves symbols and precision only for
+display and CSV output. Assets with the same peg remain separate.
+
 Payroll confirmation restores a saved run before enabling submission. An
 uncertain run keeps its period, amounts, recipients, and SDK request key across
 close/reopen and reload. Its fields remain fixed until Core confirms success or terminal closure.
@@ -98,6 +103,16 @@ The testing harness uses the real public provider and controllers and imports
 its client factory only through `@capxul/sdk/testing`; it owns no renderer or
 parallel identity state.
 
+## Activity documents
+
+`CapxulActivity.Detail` exposes `documents`, `selectedDocument`, and
+`selectDocument({ documentHash, contentHash })`. Selection defaults to the
+instruction, then the Movement Memo. `renderDocument()` returns safe semantic
+HTML. `downloadDocument()` returns exact bytes for a deliberate download.
+The host owns the panel and download action. Do not log these results.
+Account or Organization changes clear selection and cancel pending reads.
+These methods replace the receipt-only selector and action.
+
 ## Documentation
 
 - [Maintainer context](./CONTEXT.md)

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { A as entered, C as CreateOrganizationFailure, D as OrganizationDetails, E as InvocationOptions, F as useCapxulTransitions, M as useCapxulDestination, N as useCapxulIdentity, O as ProfileDetails, P as useCapxulSend, S as CapxulSend, T as Destination, _ as ReadyDestination, a as AuthenticationSlots, b as Slot, c as ControllerAction, d as OnboardingControllerProps, f as OrgFailure, g as ProfileSlotProps, h as PendingAuthState, i as AuthenticatedState, j as useCapxulAuth, k as SendResult, l as FaultedState, m as OtpPendingState, n as AccountProgress, o as CapxulAuthenticationController, p as OrgProgress, r as ActionResult, s as CapxulOnboardingController, t as AccountFailure, u as NavigationAction, v as RetryAction, w as CreateOrganizationSubmission, x as CapxulAuth, y as SignedOutState } from "./controllers-BWmKRFy6.mjs";
 import { ReactNode, RefCallback } from "react";
 import { QueryClient, UseMutationResult, UseQueryResult } from "@tanstack/react-query";
-import { Account, AccountRequirement, ActivityAnnotation, ActivityAnnotationInput, ActivityDetail, ActivityKind, ActivityListParams, ActivityPage, ActivityPhase, ActivityRange, ActivityReference, ActorReference, AddressBookEntry, BudgetId, CapxulClient, CapxulError, CapxulResult, CapxulSigner, CreateOrgInput, CurrentHoldings, HostObservability, IdentityDestination, IdentityState, InviteMemberInput, MemberView, Money, MoneyParseErrorReason, OrgId, OrgView, OrganizationPaymentBatchInput, OrganizationPaymentInput, PartyId, Payment, PaymentDirection, PaymentDocumentRef, PaymentDocumentRender, PaymentStatus, PaymentTiming, PaymentType, PaymentsPayInput, PayrollGroupId, PayrollGroupInput, PayrollRunId, PayrollRunStatus, Permission, PermissionMethods, PermissionReadResult, Profile, RoleView, SubmittedPermissionExecution, isClaimed, isRestoring } from "@capxul/sdk";
+import { Account, AccountRequirement, ActivityAnnotation, ActivityAnnotationInput, ActivityDetail, ActivityKind, ActivityListParams, ActivityPage, ActivityPhase, ActivityRange, ActivityReference, ActivitySummaryTotal, ActorReference, AddressBookEntry, AssetAmount, AssetId, BudgetId, CapxulClient, CapxulError, CapxulResult, CapxulSigner, CreateOrgInput, CurrentHoldings, HostObservability, IdentityDestination, IdentityState, InviteMemberInput, MemberView, Money, MoneyParseErrorReason, OrgId, OrgView, OrganizationAccess, OrganizationPaymentBatchInput, OrganizationPaymentInput, PartyId, Payment, PaymentDirection, PaymentDocumentDownload, PaymentDocumentReadRef, PaymentDocumentRef, PaymentDocumentRender, PaymentStatus, PaymentTiming, PaymentType, PaymentsPayInput, PayrollGroupId, PayrollGroupInput, PayrollRunId, PayrollRunStatus, Permission, PermissionMethods, PermissionReadResult, Profile, RoleView, SubmittedPermissionExecution, isClaimed, isRestoring } from "@capxul/sdk";
 //#region src/provider.d.ts
 type CapxulProviderSharedProps = {
   /** Bring your own QueryClient; otherwise the provider creates one. */
@@ -82,7 +82,7 @@ declare function useCapxulAccountBalance(options?: UseCapxulAccountBalanceOption
 //#region src/hooks/use-capxul-account-fund.d.ts
 type UseCapxulAccountFundReturn = UseMutationResult<{
   readonly txHash: string;
-}, CapxulError, Money>;
+}, CapxulError, AssetAmount>;
 declare function useCapxulAccountFund(): UseCapxulAccountFundReturn;
 //#endregion
 //#region src/hooks/use-capxul-money.d.ts
@@ -148,7 +148,7 @@ declare function useCapxulHoldings(params?: UseCapxulHoldingsParams): UseQueryRe
  * List the Organizations that the current user can access. Binds directly to
  * the locked `capxul.orgs()` SDK method.
  */
-type UseCapxulOrgsReturn = UseQueryResult<readonly OrgView[], CapxulError>;
+type UseCapxulOrgsReturn = UseQueryResult<readonly OrganizationAccess[], CapxulError>;
 type UseCapxulOrgsOptions = {
   /**
    * Gate the query on auth readiness. `client.orgs()` is a session-scoped
@@ -525,8 +525,8 @@ type ActivityRow = {
  */
 type SummaryWindow = "all" | "last30days" | ActivityRange;
 /**
- * Finished money strings for ONE currency bucket, so no consumer indexes an
- * array of per-currency totals. All four strings are `null` and `count` is `0`
+ * Finished valuation strings in the display currency. Unrated assets remain
+ * separate. All four strings are `null` and `count` is `0`
  * when the window holds no activity — we say there is nothing, the app says it
  * in its own words.
  */
@@ -537,6 +537,7 @@ interface ActivitySummarySlice {
   readonly moneyOut: string | null;
   readonly net: string | null;
   readonly pending: string | null;
+  readonly unrated: readonly ActivitySummaryTotal[];
   /** A count is not money, so it is not formatted. */
   readonly count: number;
   readonly isLoading: boolean;
@@ -600,9 +601,12 @@ interface ActivityLoadMoreSlice {
 interface ActivityDetailSlice {
   /** Current Payment state from the existing detail read; absent for Movements. */
   readonly payment?: Pick<Payment, "status" | "execution">;
-  /** ONE finished document, never the array, so no consumer writes `documents[0]`. */
-  readonly receiptDocument: PaymentDocumentRef | null;
-  readonly openReceiptDocument: () => Promise<PaymentDocumentRender>;
+  readonly documents: readonly PaymentDocumentRef[];
+  readonly selectedDocument: PaymentDocumentRef | null;
+  readonly selectDocument: (ref: PaymentDocumentReadRef) => void;
+  readonly renderDocument: () => Promise<PaymentDocumentRender>;
+  /** Return exact bytes on a deliberate action. The host owns the download URL. */
+  readonly downloadDocument: () => Promise<PaymentDocumentDownload>;
   readonly isOpeningDocument: boolean;
   readonly memo: string;
   readonly setMemo: (text: string) => void;
@@ -708,7 +712,7 @@ type SentPayment = {
   /** The backend payment row. */
   readonly payment: Payment;
   /** What we parsed and sent — `.value` is the comma-stripped major-unit string. */
-  readonly amount: Money;
+  readonly amount: AssetAmount;
   /** The trimmed text the person typed — the app's success toast interpolates it. */
   readonly recipient: string;
 };
@@ -741,7 +745,7 @@ interface SendMoneySourceSlice {
   readonly isPending: boolean;
 }
 interface SendMoneyAssetOption {
-  readonly id: string;
+  readonly id: AssetId;
   readonly symbol: string;
   readonly availableDisplay: string;
 }
@@ -1010,7 +1014,7 @@ interface PayrollRunAmountEntry {
   /** True while the value is one we seeded and the employer has not edited. */
   readonly prefilled: boolean;
   /** The treasury asset's currency. Rows stay absent until this value exists. */
-  readonly currency: Money["currency"];
+  readonly currency: string;
 }
 interface PayrollRunAmountsSlice {
   readonly entries: readonly PayrollRunAmountEntry[];

package/dist/index.mjs

@@ -2,7 +2,7 @@
 import { _ as useCapxul, a as useCapxulAuth, c as useCapxulIdentityOrNull, d as toInvocationControls, f as toInvocationOptions, g as useCapxulClientOrNull, h as capxulKeys, i as entered, l as useCapxulSend, m as actingAccount, n as CapxulOnboardingController, o as useCapxulDestination, p as accountKey, r as CapxulProvider, s as useCapxulIdentity, t as CapxulAuthenticationController, u as useCapxulTransitions } from "./controllers-L1UqwWS1.mjs";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { CAPXUL_OPERATIONS, CapxulError, EVM_ADDRESS_RE, Errors, HANDLE_RE, PAYMENT_DIRECTIONS, PAYMENT_STATUSES, fingerprintPaymentIntent, formatAssetAmount, formatMoney, isCapxulError, isClaimed, isClaimed as isClaimed$1, isMoneyParseError, isRestoring, isRestoring as isRestoring$1, parseMoney, paymentPhase, positionPeg, resolveIdentityDestination, toEvmAddress, toPartyId } from "@capxul/sdk";
+import { CAPXUL_OPERATIONS, CapxulError, EVM_ADDRESS_RE, Errors, HANDLE_RE, PAYMENT_DIRECTIONS, PAYMENT_STATUSES, assetSymbolFor, fingerprintPaymentIntent, formatAssetAmount, formatMoney, isCapxulError, isClaimed, isClaimed as isClaimed$1, isMoneyParseError, isRestoring, isRestoring as isRestoring$1, parseAssetAmount, parseMoney, paymentPhase, requireAsset, resolveIdentityDestination, toEvmAddress, toPartyId, toRaw, valueActivitySummary } from "@capxul/sdk";
 import { Fragment, jsx } from "react/jsx-runtime";
 //#region src/internal/require-bootstrapped-client.ts
 /**
@@ -1141,15 +1141,8 @@ function useActivityEnabled() {
 }
 //#endregion
 //#region src/headless/activity/detail.ts
-/**
-* ONE finished document, never the array, so no consumer writes `documents[0]`:
-* the payslip, else the receipt, else nothing. Those two kinds are the ones the
-* Download receipt button is for. A Movement detail carries no documents.
-*/
-function pickReceiptDocument(detail) {
-	if (detail === null || detail.kind !== "payment") return null;
-	const documents = detail.payment.documents;
-	return documents.find((document) => document.kind === "payslip") ?? documents.find((document) => document.kind === "receipt") ?? null;
+function detailDocuments(detail) {
+	return detail === null ? [] : detail.kind === "payment" ? detail.payment.documents : detail.documents;
 }
 /**
 * The root actor and the whole reference are included. A payment reference can
@@ -1184,27 +1177,76 @@ function useActivityDetail(reference, actor) {
 	const enabled = useActivityEnabled() && reference !== void 0;
 	const detail = useQuery({
 		queryKey: accountKey(capxulKeys.activityDetail(reference, actor), identity),
-		queryFn: async () => {
+		queryFn: async ({ signal }) => {
 			if (reference === void 0) throw Errors.invalidInput("reference", "required for activity.get");
-			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.get).activity.get(reference, actor === void 0 ? void 0 : { actor }));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.get).activity.get(reference, {
+				...actor === void 0 ? {} : { actor },
+				signal
+			}));
 		},
 		enabled
 	});
-	const receiptDocument = pickReceiptDocument(detail.data ?? null);
+	const documents = detailDocuments(detail.data ?? null);
+	const [selected, setSelected] = useState(null);
+	const selectedDocument = (selected === null ? void 0 : documents.find((doc) => doc.documentHash === selected.documentHash && doc.contentHash === selected.contentHash)) ?? documents.find((doc) => doc.role === "instruction") ?? documents.find((doc) => doc.role === "movement") ?? documents[0] ?? null;
+	const pending = useRef(/* @__PURE__ */ new Set());
+	const mounted = useRef(true);
+	useEffect(() => {
+		mounted.current = true;
+		const reads = pending.current;
+		return () => {
+			mounted.current = false;
+			for (const read of reads) read.abort();
+			reads.clear();
+		};
+	}, []);
+	const selectDocument = useCallback((ref) => {
+		if (!documents.some((doc) => doc.documentHash === ref.documentHash && doc.contentHash === ref.contentHash)) throw Errors.invalidInput("documentHash", "document not found");
+		for (const read of pending.current) read.abort();
+		pending.current.clear();
+		setIsOpeningDocument(false);
+		setSelected({
+			documentHash: ref.documentHash,
+			contentHash: ref.contentHash
+		});
+	}, [documents]);
 	const [isOpeningDocument, setIsOpeningDocument] = useState(false);
-	const openReceiptDocument = useCallback(async () => {
-		if (reference === void 0 || receiptDocument === null) throw Errors.invalidInput("receiptDocument", "no renderable document on this row");
+	const readDocument = useCallback(async (download) => {
+		const operation = download ? CAPXUL_OPERATIONS.paymentDocuments.get : CAPXUL_OPERATIONS.paymentDocuments.render;
+		if (!mounted.current) throw Errors.cancelled({ operation });
+		if (reference === void 0 || selectedDocument === null) throw Errors.invalidInput("documentHash", "no document on this row");
+		const controller = new AbortController();
+		pending.current.add(controller);
 		setIsOpeningDocument(true);
 		try {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.paymentDocuments.render).paymentDocuments.render(receiptDocument.documentHash));
+			const bootstrapped = requireBootstrappedClient(client, download ? CAPXUL_OPERATIONS.paymentDocuments.get : CAPXUL_OPERATIONS.paymentDocuments.render);
+			const pair = {
+				documentHash: selectedDocument.documentHash,
+				contentHash: selectedDocument.contentHash
+			};
+			const options = { signal: controller.signal };
+			const result = download ? await bootstrapped.paymentDocuments.get(pair, options) : await bootstrapped.paymentDocuments.render(pair, options);
+			if (controller.signal.aborted) throw Errors.cancelled({ operation });
+			return unwrapCapxulResult(result);
 		} finally {
-			setIsOpeningDocument(false);
+			pending.current.delete(controller);
+			if (!controller.signal.aborted) setIsOpeningDocument(pending.current.size > 0);
 		}
 	}, [
 		client,
-		receiptDocument,
+		selectedDocument,
 		reference
 	]);
+	const renderDocument = useCallback(async () => {
+		const result = await readDocument(false);
+		if (!("html" in result)) throw Errors.invalidInput("documentHash", "invalid document render");
+		return result;
+	}, [readDocument]);
+	const downloadDocument = useCallback(async () => {
+		const result = await readDocument(true);
+		if (!("bytesBase64" in result)) throw Errors.invalidInput("documentHash", "invalid document download");
+		return result;
+	}, [readDocument]);
 	const [typed, setTyped] = useState(null);
 	const annotate = useCapxulAnnotateMovement();
 	const saveMemo = useCallback(async () => {
@@ -1233,8 +1275,11 @@ function useActivityDetail(reference, actor) {
 			status: detail.data.payment.status,
 			...detail.data.payment.execution === void 0 ? {} : { execution: detail.data.payment.execution }
 		} } : {},
-		receiptDocument,
-		openReceiptDocument,
+		documents,
+		selectedDocument,
+		selectDocument,
+		renderDocument,
+		downloadDocument,
 		isOpeningDocument,
 		memo: typed ?? detail.data?.annotation?.memo ?? "",
 		setMemo: setTyped,
@@ -1247,6 +1292,7 @@ function useActivityDetail(reference, actor) {
 //#endregion
 //#region src/headless/activity/summary.ts
 const DAY_MS = 864e5;
+const display = (money) => money === null ? null : formatMoney(money);
 /**
 * `"last30days"` is the last 30 whole UTC days including today. Quantizing to
 * the UTC day keeps the cache key stable for a whole day instead of changing on
@@ -1257,52 +1303,6 @@ function resolveWindow(window, now) {
 	if (window === "last30days") return { from: Math.floor(now / DAY_MS) * DAY_MS - 29 * DAY_MS };
 	return window;
 }
-/** An integer raw-unit string lifted into a major-unit decimal string. */
-function majorUnits(raw, decimals) {
-	const negative = raw.startsWith("-");
-	const digits = negative ? raw.slice(1) : raw;
-	const sign = negative ? "-" : "";
-	if (decimals === 0) return `${sign}${digits}`;
-	const padded = digits.padStart(decimals + 1, "0");
-	const cut = padded.length - decimals;
-	return `${sign}${padded.slice(0, cut)}.${padded.slice(cut)}`;
-}
-function absoluteNet(total) {
-	const net = BigInt(total.net);
-	return net < 0n ? -net : net;
-}
-/**
-* Buckets carry different `decimals`, so their raw integers are not comparable.
-* Both are scaled to the wider precision before the magnitudes are ordered.
-*/
-function compareNet(left, right) {
-	const width = Math.max(left.decimals, right.decimals);
-	const scaledLeft = absoluteNet(left) * 10n ** BigInt(width - left.decimals);
-	const scaledRight = absoluteNet(right) * 10n ** BigInt(width - right.decimals);
-	if (scaledLeft === scaledRight) return 0;
-	return scaledLeft < scaledRight ? -1 : 1;
-}
-/**
-* Which currency `.Summary` shows: the bucket matching `primaryCurrency` when
-* one is given, else the bucket with the largest absolute `net`, breaking a tie
-* on currency code ascending so the choice is stable across reloads.
-*/
-function pickBucket(totals, primaryCurrency) {
-	if (primaryCurrency !== null) {
-		const matched = totals.find((total) => total.currency === primaryCurrency);
-		if (matched !== void 0) return matched;
-	}
-	let best = null;
-	for (const total of totals) {
-		if (best === null) {
-			best = total;
-			continue;
-		}
-		const order = compareNet(total, best);
-		if (order > 0 || order === 0 && total.currency < best.currency) best = total;
-	}
-	return best;
-}
 /**
 * The current UTC day number, which advances ON ITS OWN at UTC midnight.
 *
@@ -1346,42 +1346,36 @@ function useActivitySummary(actor, window) {
 			const params = {};
 			if (actor !== void 0) params.actor = actor;
 			if (range !== void 0) params.window = range;
-			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.summary).activity.summary(params));
-		},
-		enabled
-	});
-	const primary = useQuery({
-		queryKey: accountKey([...capxulKeys.holdings(actor), "primary"], identity),
-		queryFn: async () => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.holdings.primary).holdings.primary(actor === void 0 ? void 0 : { actor }));
+			const result = unwrapCapxulResult(await requireBootstrappedClient(client, CAPXUL_OPERATIONS.activity.summary).activity.summary(params));
+			return {
+				...result,
+				valuation: valueActivitySummary(result.totals)
+			};
 		},
 		enabled
 	});
 	const totals = summary.data?.totals;
-	const isLoading = summary.isLoading || primary.isLoading;
-	const bucket = useMemo(() => totals === void 0 || isLoading ? null : pickBucket(totals, null), [isLoading, totals]);
-	if (bucket === null) return {
+	const isLoading = summary.isLoading;
+	if (summary.data === void 0 || totals === void 0 || totals.length === 0 || isLoading) return {
 		currency: null,
 		moneyIn: null,
 		moneyOut: null,
 		net: null,
 		pending: null,
+		unrated: [],
 		count: summary.data?.count ?? 0,
 		isLoading,
 		error: asCapxulError$1(summary.error),
 		...summary.data?.readWarning === void 0 ? {} : { readWarning: summary.data.readWarning }
 	};
-	const display = (raw) => formatMoney({
-		currency: bucket.currency,
-		value: majorUnits(raw, bucket.decimals),
-		decimals: bucket.decimals
-	});
+	const valuation = summary.data.valuation;
 	return {
-		currency: bucket.currency,
-		moneyIn: display(bucket.in),
-		moneyOut: display(bucket.out),
-		net: display(bucket.net),
-		pending: display(bucket.pendingIn),
+		currency: valuation.moneyIn?.currency ?? null,
+		moneyIn: display(valuation.moneyIn),
+		moneyOut: display(valuation.moneyOut),
+		net: display(valuation.net),
+		pending: display(valuation.pending),
+		unrated: valuation.unrated,
 		count: summary.data?.count ?? 0,
 		isLoading,
 		error: asCapxulError$1(summary.error),
@@ -1408,7 +1402,7 @@ const SIGN = Object.freeze({
 	self: ""
 });
 function toActivityRow(item, actor) {
-	const amountDisplay = formatMoney(item.amount);
+	const amountDisplay = formatAssetAmount(item.amount);
 	const signedAmountDisplay = `${SIGN[item.direction]}${amountDisplay}`;
 	if (item.kind === "movement") return {
 		kind: "movement",
@@ -1420,7 +1414,7 @@ function toActivityRow(item, actor) {
 		counterpartyLabel: item.counterpartyLabel,
 		amountDisplay,
 		signedAmountDisplay,
-		currency: item.amount.currency,
+		currency: assetSymbolFor(item.amount.asset),
 		createdAt: item.createdAt,
 		classification: item.classification,
 		phase: MOVEMENT_PHASE,
@@ -1442,7 +1436,7 @@ function toActivityRow(item, actor) {
 		counterpartyLabel: item.counterpartyLabel,
 		amountDisplay,
 		signedAmountDisplay,
-		currency: item.amount.currency,
+		currency: assetSymbolFor(item.amount.asset),
 		createdAt: item.createdAt,
 		ledgerKind: item.ledgerKind,
 		paymentType: item.paymentType,
@@ -1523,7 +1517,7 @@ function buildCsv(items, actor, search) {
 			row.counterpartyLabel,
 			row.direction,
 			item.amount.value,
-			item.amount.currency,
+			assetSymbolFor(item.amount.asset),
 			row.kind === "payment" ? row.execution?.notSent ? "not_sent" : row.execution?.status === "unresolved" ? "verifying" : row.status : "",
 			row.reference.id,
 			row.receipt?.transactionHash ?? ""
@@ -1873,18 +1867,19 @@ function useOrgMeReading(orgId) {
 //#endregion
 //#region src/internal/write-names-asset.ts
 /**
-* Identity law 5 (`docs/campaigns/capabilities/treasury-cut/HANDOFF.md`): "A
-* payment names an asset or inherits it from an authorized fact. Missing asset
-* refuses."
+* Identity law: "A payment names an asset or inherits it from an authorized
+* fact. Missing asset refuses." The rule was recorded in the retired
+* treasury-cut handoff (removed from the current tree by the exact-asset
+* contraction; its record survives in Git history).
 *
 * A Capxul payment writer takes `PaymentMoney` — a peg currency, a value and
 * `decimals` — and settles one fixed legacy token. No `AssetId` crosses that
 * seam, so a payment composed from a named position cannot name the asset it
 * moves: a position selected as USDT authorizes a different token.
 *
-* `false` until slice 02 (`02-named-pay`) makes the writer take the command's
-* asset. The Send and Payroll composers read this to refuse a submission
-* rather than authorize a token the person did not pick.
+* `false` until the writer takes the command's asset. The Send and Payroll
+* composers read this to refuse a submission rather than authorize a token the
+* person did not pick.
 */
 function writeNamesAsset() {
 	return false;
@@ -2054,7 +2049,6 @@ function useSelectedOption(options) {
 function assetSelectionsFromAccount$1(account) {
 	if (account === null) return [];
 	return account.balances.map((position) => {
-		const peg = positionPeg(position.asset);
 		return {
 			option: {
 				id: position.asset,
@@ -2064,10 +2058,9 @@ function assetSelectionsFromAccount$1(account) {
 					value: position.available
 				})
 			},
-			money: peg === null ? null : {
-				currency: peg,
-				value: position.available,
-				decimals: position.decimals
+			money: {
+				asset: position.asset,
+				value: position.available
 			}
 		};
 	});
@@ -2089,7 +2082,7 @@ function useSendMoney(input) {
 	const [selectedAssetOption, selectAsset] = useSelectedOption(assetOptions);
 	const selectedAssetMoney = useMemo(() => assetSelections.find((selection) => selection.option.id === selectedAssetOption?.id)?.money ?? null, [assetSelections, selectedAssetOption]);
 	const [amountText, setAmountText] = useState("");
-	const parsed = useMemo(() => selectedAssetMoney === null || amountText.trim() === "" ? null : parseMoney(amountText, selectedAssetMoney), [amountText, selectedAssetMoney]);
+	const parsed = useMemo(() => selectedAssetMoney === null || amountText.trim() === "" ? null : parseAssetAmount(amountText, requireAsset(selectedAssetMoney.asset)), [amountText, selectedAssetMoney]);
 	const parsedMoney = parsed !== null && !isMoneyParseError(parsed) ? parsed : null;
 	const amountError = parsed !== null && isMoneyParseError(parsed) ? parsed.reason : null;
 	const recipient = useRecipientResolution(client, JSON.stringify([
@@ -2538,11 +2531,6 @@ const CapxulDashboardAccess = Object.assign(Root$3, {
 });
 //#endregion
 //#region src/headless/payroll/money.ts
-/** `{ value: "12.34", decimals: 6 }` → `12340000n`. */
-function toMinorUnits(money) {
-	const [whole = "0", fraction = ""] = money.value.split(".");
-	return BigInt(`${whole}${fraction.padEnd(money.decimals, "0")}`);
-}
 const TYPED_AMOUNT = /^(-?)(\d+)(?:\.(\d+))?$/;
 /**
 * Σ of the employer's TYPED amounts on a saved group — a DISPLAY total.
@@ -2575,6 +2563,17 @@ function fromMinorUnits(raw, asset) {
 		decimals: asset.decimals
 	};
 }
+/** Convert exact raw units to one asset quantity without a fiat denomination. */
+function assetFromMinorUnits(raw, asset) {
+	const money = fromMinorUnits(raw, {
+		currency: "USD",
+		decimals: asset.decimals
+	});
+	return {
+		asset: asset.asset,
+		value: money.value
+	};
+}
 //#endregion
 //#region src/headless/payroll/reads.ts
 function toRecipientOption(entry) {
@@ -2691,7 +2690,7 @@ function scopedClient(client, method, orgId) {
 //#endregion
 //#region src/headless/payroll/use-payroll.ts
 /** Money reads the same way everywhere on this screen: amount then code. */
-const GRAMMAR$1 = { grammar: "code" };
+const GRAMMAR = { grammar: "code" };
 /**
 * One captured snapshot, or nothing — never a fabricated empty options object,
 * and never a DOM event a screen wired straight to `onClick`.
@@ -2707,7 +2706,7 @@ function toPayrollGroupRow(group) {
 		name: group.name,
 		tone: group.tone,
 		memberCount: group.members.length,
-		totalDisplay: currency === void 0 ? "" : formatMoney(sumTypedAmounts(group.members.map((member) => member.amount), currency), GRAMMAR$1),
+		totalDisplay: currency === void 0 ? "" : formatMoney(sumTypedAmounts(group.members.map((member) => member.amount), currency), GRAMMAR),
 		members: group.members.map((member) => ({
 			recipientId: member.partyId,
 			amount: member.amount,
@@ -2797,8 +2796,8 @@ function usePayroll(orgId) {
 	const started = orgId !== void 0;
 	return {
 		summary: {
-			walletBalanceDisplay: treasury.data === void 0 ? null : formatMoney(treasury.data.available, GRAMMAR$1),
-			paidThisMonthDisplay: runs.data === void 0 ? null : formatMoney(runs.data.settledThisMonth, GRAMMAR$1),
+			walletBalanceDisplay: treasury.data?.available === void 0 || treasury.data.available === null ? null : formatMoney(treasury.data.available, GRAMMAR),
+			paidThisMonthDisplay: runs.data === void 0 ? null : runs.data.settledThisMonth.map(formatAssetAmount).join(", "),
 			isLoading: started && (treasury.data === void 0 && treasury.error === null || runs.data === void 0 && runs.error === null),
 			error: treasury.error ?? runs.error
 		},
@@ -2882,8 +2881,9 @@ function decodeDraft(value, scope) {
 	const items = input.items.map((raw) => {
 		const item = record(raw);
 		const to = record(item.to);
+		const amount = record(item.amount);
 		const partyId = toPartyId(identifier(item.partyId));
-		if (to.kind !== "party" || to.partyId !== partyId || item.gross !== item.net || !Array.isArray(item.adjustments) || item.adjustments.length !== 0) throw Errors.invalidInput("payrollDraft", "Invalid draft recipient");
+		if (to.kind !== "party" || to.partyId !== partyId || item.gross !== item.net || typeof amount.asset !== "string" || typeof amount.value !== "string" || typeof item.currency !== "string" || typeof item.decimals !== "number" || !Number.isInteger(item.decimals) || !Array.isArray(item.adjustments) || item.adjustments.length !== 0) throw Errors.invalidInput("payrollDraft", "Invalid draft recipient");
 		const net = minorAmount(item.net);
 		return {
 			to: {
@@ -2891,12 +2891,20 @@ function decodeDraft(value, scope) {
 				partyId
 			},
 			partyId,
+			amount: {
+				asset: requireAsset(amount.asset).assetId,
+				value: amount.value
+			},
 			gross: net,
 			net,
+			currency: item.currency,
+			decimals: item.decimals,
 			adjustments: []
 		};
 	});
 	if (new Set(items.map((item) => item.partyId)).size !== items.length) throw Errors.invalidInput("payrollDraft", "Duplicate draft recipient");
+	const exactAsset = requireAsset(identifier(asset.id));
+	if (items.some((item) => item.amount.asset !== exactAsset.assetId)) throw Errors.invalidInput("payrollDraft", "Draft item asset does not match the run asset");
 	return {
 		version: 1,
 		scope,
@@ -2907,6 +2915,7 @@ function decodeDraft(value, scope) {
 		},
 		input: {
 			permissionId: identifier(input.permissionId),
+			asset: exactAsset.assetId,
 			period: {
 				start: period.start,
 				end: period.start
@@ -3110,7 +3119,6 @@ function termsSeeds(terms, asset, period) {
 }
 //#endregion
 //#region src/headless/payroll/use-payroll-run.ts
-const GRAMMAR = { grammar: "code" };
 /**
 * The period this composer composes: an INSTANT run (ruling Q3). `authorizeRun`
 * stamps `start === end === runAt` at submit, and the payslip's period renders
@@ -3134,6 +3142,32 @@ const INSTANT_RUN_PERIOD = {
 function amountText(amounts, seeds, recipientId) {
 	return amounts[recipientId]?.value ?? seeds.get(recipientId) ?? "";
 }
+function freshRunItems(input) {
+	const items = [];
+	for (const [index, recipientId] of input.selected.entries()) {
+		const to = input.payableRefs[index];
+		const amount = input.amounts[index];
+		const terms = input.compensationTerms.get(recipientId);
+		if (to === void 0 || amount === void 0 || terms === void 0) throw Errors.unknown();
+		items.push({
+			to: {
+				kind: "party",
+				partyId: toPartyId(recipientId)
+			},
+			partyId: recipientId,
+			amount,
+			gross: terms.rate,
+			net: terms.rate,
+			currency: terms.currency,
+			decimals: terms.decimals,
+			adjustments: []
+		});
+	}
+	return items;
+}
+function hasRequiredCompensation(frozen, writerNamesSelectedAsset, selected, terms) {
+	return frozen || !writerNamesSelectedAsset || selected.every((recipientId) => terms.has(recipientId));
+}
 /**
 * WHICH run the composer is composing, by MEANING rather than by object shape.
 *
@@ -3176,7 +3210,6 @@ function initialAmounts(prefill) {
 function assetSelectionsFromAccount(account) {
 	if (account === null) return [];
 	return account.balances.map((position) => {
-		const peg = positionPeg(position.asset);
 		return {
 			option: {
 				id: position.asset,
@@ -3186,10 +3219,9 @@ function assetSelectionsFromAccount(account) {
 					value: position.available
 				})
 			},
-			money: peg === null ? null : {
-				currency: peg,
-				value: position.available,
-				decimals: position.decimals
+			money: {
+				asset: position.asset,
+				value: position.available
 			}
 		};
 	});
@@ -3207,17 +3239,13 @@ function usePayrollRun(input) {
 	const terms = useOrgTerms(orgId);
 	const [selected, setSelected] = useState(() => prefill?.recipientIds ?? []);
 	const [amounts, setAmounts] = useState(() => initialAmounts(prefill));
-	const restoreCurrency = treasury.data?.available.currency;
 	const { draftScope, currentScope, draft, draftError, restorationPending, activateDraft, restoreDraft, setDraft, recovery, draftBlocked } = useRunDraft(client, orgId, useCallback((restored) => {
 		setSelected(restored.input.items.map((item) => item.partyId));
-		if (restoreCurrency !== void 0 && restoreCurrency === restored.asset.currency) setAmounts(Object.fromEntries(restored.input.items.map((item) => [item.partyId, {
-			value: fromMinorUnits(BigInt(item.net), {
-				currency: restoreCurrency,
-				decimals: restored.asset.decimals
-			}).value,
+		if (requireAsset(restored.input.asset).assetId === restored.input.asset) setAmounts(Object.fromEntries(restored.input.items.map((item) => [item.partyId, {
+			value: item.amount.value,
 			prefilled: false
 		}])));
-	}, [restoreCurrency]));
+	}, []));
 	const frozen = draft !== null;
 	const composerKey = composerIdentity(orgId, prefill, draftScope, frozen);
 	const [seededKey, setSeededKey] = useState(composerKey);
@@ -3279,12 +3307,19 @@ function usePayrollRun(input) {
 		}
 		return resolved;
 	}, [refs, selected]);
-	const seeds = useMemo(() => termsSeeds(terms.data ?? [], assetMoney, INSTANT_RUN_PERIOD), [assetMoney, terms.data]);
+	const seeds = useMemo(() => {
+		if (assetMoney === null) return /* @__PURE__ */ new Map();
+		const metadata = requireAsset(assetMoney.asset);
+		return termsSeeds(terms.data ?? [], metadata.peg === null ? null : {
+			currency: metadata.peg,
+			decimals: metadata.decimals
+		}, INSTANT_RUN_PERIOD);
+	}, [assetMoney, terms.data]);
 	const entries = useMemo(() => {
 		if (assetMoney === null) return [];
 		return selected.map((recipientId) => {
 			const value = amountText(amounts, seeds, recipientId);
-			const parsed = value.trim() === "" ? null : parseMoney(value, assetMoney);
+			const parsed = value.trim() === "" ? null : parseAssetAmount(value, requireAsset(assetMoney.asset));
 			return {
 				recipientId,
 				name: named.get(recipientId)?.name ?? recipientId,
@@ -3292,7 +3327,7 @@ function usePayrollRun(input) {
 				change: (text) => change(recipientId, text),
 				error: parsed !== null && isMoneyParseError(parsed) ? parsed.reason : null,
 				prefilled: amounts[recipientId]?.prefilled ?? seeds.has(recipientId),
-				currency: assetMoney.currency
+				currency: requireAsset(assetMoney.asset).symbol
 			};
 		});
 	}, [
@@ -3307,7 +3342,7 @@ function usePayrollRun(input) {
 		if (assetMoney === null || selected.length === 0) return null;
 		const money = [];
 		for (const recipientId of selected) {
-			const parsed = parseMoney(amountText(amounts, seeds, recipientId), assetMoney);
+			const parsed = parseAssetAmount(amountText(amounts, seeds, recipientId), requireAsset(assetMoney.asset));
 			if (isMoneyParseError(parsed)) return null;
 			money.push(parsed);
 		}
@@ -3318,17 +3353,25 @@ function usePayrollRun(input) {
 		seeds,
 		selected
 	]);
-	const total = useMemo(() => parsedAmounts === null || assetMoney === null ? null : fromMinorUnits(parsedAmounts.reduce((sum, money) => sum + toMinorUnits(money), 0n), assetMoney), [assetMoney, parsedAmounts]);
-	const availableRaw = assetMoney === null ? null : toMinorUnits(assetMoney);
-	const totalRaw = total === null ? null : toMinorUnits(total);
+	const total = useMemo(() => parsedAmounts === null || assetMoney === null ? null : {
+		asset: assetMoney.asset,
+		value: assetFromMinorUnits(parsedAmounts.reduce((sum, amount) => sum + toRaw(amount, requireAsset(amount.asset)), 0n), {
+			asset: assetMoney.asset,
+			decimals: requireAsset(assetMoney.asset).decimals
+		}).value
+	}, [assetMoney, parsedAmounts]);
+	const availableRaw = assetMoney === null ? null : toRaw(assetMoney, requireAsset(assetMoney.asset));
+	const totalRaw = total === null ? null : toRaw(total, requireAsset(total.asset));
 	const funds = availableRaw === null || totalRaw === null ? "unknown" : totalRaw > availableRaw ? "insufficient" : "available";
 	const budgets = me.data?.budgets ?? [];
+	const compensationTerms = useMemo(() => new Map((terms.data ?? []).filter((row) => row.unit === "paycheck" && /^[1-9][0-9]*$/u.test(row.rate)).map((row) => [row.partyId, row])), [terms.data]);
+	const writerNamesSelectedAsset = writeNamesAsset();
 	const blockedReason = firstFalseFact({
 		signerReady: signerStatus === "ready",
 		...runAuthorityFacts(draft, budgets, selectedAsset, assetMoney, funds),
 		recipientCount: payableRefs === null ? 0 : selected.length,
-		amountsParse: total !== null,
-		writeNamesAsset: writeNamesAsset()
+		amountsParse: total !== null && hasRequiredCompensation(frozen, writerNamesSelectedAsset, selected, compensationTerms),
+		writeNamesAsset: writerNamesSelectedAsset
 	});
 	const authorize = useMutation({
 		mutationFn: async ({ candidate, options }) => {
@@ -3350,7 +3393,7 @@ function usePayrollRun(input) {
 			if (candidate.scope === currentScope.current) restoreDraft(candidate.scope);
 		}
 	});
-	const totalDisplay = total === null ? null : formatMoney(total, GRAMMAR);
+	const totalDisplay = total === null ? null : formatAssetAmount(total);
 	const authorizeMutate = authorize.mutate;
 	const submit = useCallback((options) => {
 		const attempt = toInvocationOptions(options);
@@ -3359,41 +3402,35 @@ function usePayrollRun(input) {
 		if (permissionId === void 0 || totalDisplay === null || parsedAmounts === null) return;
 		if (payableRefs === null) return;
 		const recipientCount = selected.length;
-		const items = [];
-		for (const [index, recipientId] of selected.entries()) {
-			const to = payableRefs[index];
-			const parsed = parsedAmounts[index];
-			if (to === void 0 || parsed === void 0) return;
-			const raw = toMinorUnits(parsed).toString();
-			items.push({
-				to: {
-					kind: "party",
-					partyId: toPartyId(recipientId)
-				},
-				partyId: recipientId,
-				gross: raw,
-				net: raw,
-				adjustments: []
+		let candidate;
+		if (frozen) candidate = draft;
+		else {
+			const items = freshRunItems({
+				selected,
+				payableRefs,
+				amounts: parsedAmounts,
+				compensationTerms
 			});
-		}
-		const runAt = Date.now();
-		const candidate = frozen ? draft : {
-			version: 1,
-			scope: draftScope,
-			asset: {
-				id: selectedAsset.id,
-				currency: assetMoney.currency,
-				decimals: assetMoney.decimals
-			},
-			input: {
-				permissionId,
-				period: {
-					start: runAt,
-					end: runAt
+			const runAt = Date.now();
+			candidate = {
+				version: 1,
+				scope: draftScope,
+				asset: {
+					id: selectedAsset.id,
+					currency: requireAsset(assetMoney.asset).symbol,
+					decimals: requireAsset(assetMoney.asset).decimals
 				},
-				items
-			}
-		};
+				input: {
+					permissionId,
+					asset: selectedAsset.id,
+					period: {
+						start: runAt,
+						end: runAt
+					},
+					items
+				}
+			};
+		}
 		submitGate.current = true;
 		authorizeMutate({
 			candidate,
@@ -3425,6 +3462,7 @@ function usePayrollRun(input) {
 		selectedAsset,
 		blockedReason,
 		budgets,
+		compensationTerms,
 		onFailed,
 		onRun,
 		parsedAmounts,
@@ -3473,13 +3511,20 @@ function usePayrollRun(input) {
 	};
 }
 function remainingBalanceDisplay(available, total, asset) {
-	return available === null || total === null || asset === null ? null : formatMoney(fromMinorUnits(available - total, asset), GRAMMAR);
+	if (available === null || total === null || asset === null) return null;
+	const remaining = available - total;
+	const magnitude = remaining < 0n ? -remaining : remaining;
+	const formatted = formatAssetAmount(assetFromMinorUnits(magnitude, {
+		asset: asset.asset,
+		decimals: requireAsset(asset.asset).decimals
+	}));
+	return remaining < 0n ? `-${formatted}` : formatted;
 }
 /** Persisted replay keeps its authorized Budget and asset; a prior debit cannot block its own recovery. */
 function runAuthorityFacts(draft, budgets, asset, money, funds) {
 	return {
 		budgetCount: draft !== null && !budgets.some((budget) => budget.id === draft.input.permissionId) ? 0 : budgets.length,
-		hasAsset: asset !== null && (draft === null || draft.asset.id === asset.id && draft.asset.currency === money?.currency && draft.asset.decimals === money?.decimals),
+		hasAsset: asset !== null && (draft === null || draft.asset.id === asset.id && draft.input.asset === money?.asset),
 		funds: draft?.input.requestKey === void 0 ? funds : "available"
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/sdk-react",
-  "version": "4.20.0-beta.5",
+  "version": "4.20.0-beta.6",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Xelmar-tech/infrastructure.git",
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@capxul/sdk": "4.20.0-beta.5"
+    "@capxul/sdk": "4.20.0-beta.6"
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.66.9",
@@ -43,6 +43,7 @@
     "vite": "npm:@voidzero-dev/vite-plus-core@0.3.0",
     "vite-plus": "0.3.0",
     "vitest": "4.1.11",
+    "@capxul/config": "0.4.0-beta.0",
     "@capxul/errors": "0.3.0",
     "@capxul/types": "0.3.0",
     "@capxul/typescript-config": "0.0.0"