@percayso-community/cayso-contracts 0.26.0 → 0.29.0

package/dist/assertion.d.ts

@@ -319,6 +319,28 @@
  * was served, as `'provision-citizenship'` was, and it is served at
  * `ROUTES.commercialPayment`.
  *
+ * `'make-citizen-transfer'` is a Citizen transferring Cayso from their own Citizen
+ * Wallet to another Citizen's (CAY-0088). It is not a second use of
+ * `'make-commercial-payment'`, which always has an organisation on one side, nor of
+ * `'place-quote'`, which prices cents against sterling: a transfer quotes nothing. A
+ * credential minted to place a quote must not thereby move cents to somebody without
+ * a match, nor the reverse. It is served at `ROUTES.citizenTransfer`.
+ *
+ * `'change-handle'` is a Citizen's Handle change, charged by Cayso (CAY-0091). It is
+ * not a second use of `'make-citizen-transfer'`, which pays another Citizen, nor of
+ * `'settle-marketplace-order'`, which presents Store Platform's signed order: a Handle
+ * change charges the Citizen for a Community service on the authority of a change
+ * reference Percayso ID minted. A credential minted for any other operation must not
+ * authorise a Handle change, and the reverse. It is served at `ROUTES.handleChange`,
+ * and it charges for the change reference named by
+ * {@link AssertionClaims.handleChangeReference} and no other.
+ *
+ * `'read-handle-change-receipt'` asks whether a change reference was charged
+ * (CAY-0091), as `'read-marketplace-receipt'` asks of a checkout key. It is its own
+ * operation because it is a read beside the money-grade charge it reports on: a
+ * credential minted to ask what happened must not thereby be able to make something
+ * happen. It is served at `ROUTES.handleChangeReceipt`.
+ *
  * `'place-quote'`, `'withdraw-quote'` and `'request-buy-back'` are the citizen
  * market's three acts (CAY-0080, Open decision Q). They are three operations
  * because they are three acts: a credential minted to withdraw a quote must not
@@ -363,7 +385,7 @@
  * Contribution Store's assertion, which no person presents and which therefore has
  * no operation here. It is classified before it is served.
  */
-export type ContractOperation = 'read-own-wallet' | 'read-purchase-result' | 'authorise-purchase' | 'cancel-purchase' | 'provision-citizenship' | 'read-own-citizenship' | 'provision-organisation' | 'claim-founder-wallet' | 'make-commercial-payment' | 'place-quote' | 'withdraw-quote' | 'request-buy-back' | 'read-citizen-market' | 'read-marketplace-receipt' | 'settle-marketplace-order' | 'settle-marketplace-refund' | 'present-standing-authorisation';
+export type ContractOperation = 'read-own-wallet' | 'read-purchase-result' | 'authorise-purchase' | 'cancel-purchase' | 'provision-citizenship' | 'read-own-citizenship' | 'provision-organisation' | 'claim-founder-wallet' | 'make-commercial-payment' | 'make-citizen-transfer' | 'change-handle' | 'read-handle-change-receipt' | 'place-quote' | 'withdraw-quote' | 'request-buy-back' | 'read-citizen-market' | 'read-marketplace-receipt' | 'settle-marketplace-order' | 'settle-marketplace-refund' | 'present-standing-authorisation';
 /**
  * An operation key belonging to a deployment's OWN surfaces rather than to this
  * contract — operator work, above all. Deliberately not enumerated: this package
@@ -832,6 +854,42 @@ export interface AssertionClaims {
      * of work.
      */
     readonly founderClaimReference?: string;
+    /**
+     * The change reference: the single-use, opaque value Percayso ID issued when it
+     * reserved the Citizen's proposed Handle (CAY-0091). OPTIONAL on the wire, and read by
+     * `'change-handle'` and `'read-handle-change-receipt'` and by no other operation.
+     *
+     * ## It travels with its operations, in both directions
+     *
+     * As {@link founderClaimReference} does. A credential whose `scope` carries
+     * `'change-handle'` or `'read-handle-change-receipt'` must carry this claim, and a
+     * credential that carries this claim must be scoped to one of them. A verifier refuses
+     * either half missing as a malformed credential, before any gate reads it: a Handle
+     * change with no reference charges for nothing, and a reference carried to any other
+     * operation is half of a Handle change put in front of a route with no business
+     * reading it.
+     *
+     * ## It is carried here and never in a request
+     *
+     * The reference fixes the new Handle BEFORE the charge, so a receipt cannot be spent
+     * on a different name. A reference named in a body would be the caller's claim about
+     * which Handle change is theirs (CAY-0021); inside the signed assertion it is Percayso
+     * ID's statement. Cayso charges at most once per reference, keys the charge by it, and
+     * names it in the signed receipt.
+     *
+     * ## What it is not
+     *
+     * It is NOT the Handle. Cayso never learns the Handle: the reference is opaque, and
+     * Cayso compares it and never parses it. It is not derived from a Percayso identity,
+     * and it carries no `sub`, no name and no email. This contract asks for a non-empty
+     * string and nothing more.
+     *
+     * ## It is as trustworthy as the verifier, and no more
+     *
+     * As with every claim: declaring it makes the promise structural, and a real
+     * signature check is what makes it trustworthy.
+     */
+    readonly handleChangeReference?: string;
     /**
      * The Organisation **Wallet IDs** this identity holds the mandate for
      * (CAY-0024, CAY-0059 §7). Each entry is a wallet id — the opaque identifier

package/dist/assurance.js

@@ -325,6 +325,51 @@ export const ASSURANCE_POLICY = {
             'money-grade: anything but the development bypass. The bar applies on both routes, and to ' +
             'an Authorised User it applies again at every payment, not only when the allowance was granted.',
     },
+    // A Citizen transferring to another Citizen (CAY-0088 §2). Money-grade, at the
+    // purchase path's bar, for the commercial payment's reason: value leaves a holder
+    // for somebody else, and a bar no issuer can clear would close the transfer on
+    // every deployment. An allowlist, so a future method is admissible only when
+    // somebody decides it here.
+    'make-citizen-transfer': {
+        operation: 'make-citizen-transfer',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: 'A Citizen transfer moves value out of one holder to another, so it is money-grade: ' +
+            'anything but the development bypass. An unverified holder must never be able to send, ' +
+            'because sending is how value reaches somebody else.',
+    },
+    // A Citizen paying Cayso to change their Handle (CAY-0091). Money-grade, at the
+    // Citizen transfer's bar: value leaves the holder, and the payment is what lets
+    // Percayso ID change a public name, so an unverified holder must not be able to
+    // make it. An allowlist, so a future method is admissible only when somebody
+    // decides it here.
+    'change-handle': {
+        operation: 'change-handle',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: "A Handle change charges the Citizen's own Citizen Wallet, so it is money-grade: anything " +
+            'but the development bypass. The receipt it answers with lets Percayso ID change a ' +
+            'Handle, which an unverified holder must never be able to buy.',
+    },
+    // Asking whether a change reference was charged (CAY-0091). A read: nothing moves and
+    // nothing is reserved, so it applies no bar, as the marketplace receipt read applies
+    // none. A credential scoped to it cannot charge anything.
+    'read-handle-change-receipt': {
+        operation: 'read-handle-change-receipt',
+        assurance: 'not-required',
+        rationale: 'Asking whether a change reference was charged moves nothing and reserves nothing. It ' +
+            'answers a receipt Cayso already signed, or that there was no charge, and nothing more.',
+    },
     // The citizen market's three acts (CAY-0080 §7, Open decision Q). All three are
     // money-grade and all three are allowlists, at the purchase path's bar: the acting
     // party is a Citizen, and a bar no issuer can yet clear would shut the market on
@@ -505,6 +550,9 @@ export const OPERATION_FOR_ROUTE = {
     purchaseResult: 'read-purchase-result',
     purchaseCancel: 'cancel-purchase',
     commercialPayment: 'make-commercial-payment',
+    citizenTransfer: 'make-citizen-transfer',
+    handleChange: 'change-handle',
+    handleChangeReceipt: 'read-handle-change-receipt',
     citizenMarket: 'read-citizen-market',
     placeQuote: 'place-quote',
     withdrawQuote: 'withdraw-quote',

package/dist/citizen-transfer.d.ts

@@ -0,0 +1,110 @@
+/**
+ * `citizen-transfer` — the request, the answer and the closed refusal union for a
+ * Citizen transferring Cayso to another Citizen (CAY-0088).
+ *
+ * A Citizen transfer is unrestricted cents moving directly from the caller's own
+ * Citizen Wallet to another Citizen Wallet, as one `transfer` movement. It is not a
+ * quoted sale and it is not the citizen market: no price is quoted, no sterling moves,
+ * and the Treasury takes no part. A transfer between a pair that mirrors market fills
+ * is watched for by the transfer-pattern alarm (CAY-0080 §5.8) and is reported, never
+ * reversed. Served at `ROUTES.citizenTransfer`.
+ *
+ * ## One movement or nothing, so there is no status
+ *
+ * As with the commercial payment (CAY-0079 §5) there is no sterling leg and no
+ * provider, so there is nothing to authorise first and capture later. The answer is a
+ * {@link CitizenTransferMade}, carrying the one movement that was written, or a
+ * {@link CitizenTransferRefused}, carrying one reason and meaning nothing was written.
+ *
+ * ## Replay under one key
+ *
+ * The key is unique together with the sending wallet. A repeat with the same key, the
+ * same payee and the same cents answers the movement already written, in the same
+ * shape; a repeat with the same key and anything different is refused with
+ * `idempotency_key_reused_for_a_different_transfer`. A transfer is never reversed: a
+ * Citizen who wants cents back asks for a new transfer the other way, made by the
+ * other Citizen under their own key.
+ *
+ * ## The sender is never named in the request
+ *
+ * The sending wallet is the verified assertion's subject's own Citizen Wallet,
+ * resolved inside the service (CAY-0021). A request that named the sending wallet
+ * would be the caller's claim about whose cents these are. The payee is a wallet id,
+ * given by the payee as they would give an address, and never a Percayso identity.
+ *
+ * ## What this file must not decide
+ *
+ *   - **No figures.** No ceiling, rate or threshold is restated here (CAY-0088 §4).
+ *   - **One payee.** A split is not designed.
+ *   - **Restricted cents never move.** A restricted lot is not transferable (CAY-0074),
+ *     so a wallet short of unrestricted cents is short, whatever else it holds.
+ */
+import type { Cents, Millis } from './wallet.js';
+/** A Citizen transferring cents from their own Citizen Wallet to another, under one key. */
+export interface CitizenTransferRequest {
+    /** The Citizen Wallet the cents arrive in. A wallet id, never a Percayso identity. */
+    readonly payeeWalletId: string;
+    /** Whole cents, above zero. Anything else is refused `amount_not_positive_whole_cents`. */
+    readonly cents: Cents;
+    /** Caller-generated, unique per sending wallet. The same key never moves cents twice; a repeat REPLAYS. */
+    readonly idempotencyKey: string;
+}
+/**
+ * The one movement a Citizen transfer wrote. Final and append-only. It names the
+ * sending wallet because the caller is owed the handle their own cents left from, and
+ * names no person.
+ */
+export interface CitizenTransfer {
+    /** The movement that carried the cents. */
+    readonly movementId: string;
+    readonly fromWalletId: string;
+    readonly payeeWalletId: string;
+    readonly cents: Cents;
+    readonly transferredAt: Millis;
+}
+/** The transfer was made. Answered for the request that made it and for every replay of its key. */
+export interface CitizenTransferMade {
+    readonly outcome: 'transferred';
+    readonly transfer: CitizenTransfer;
+}
+/** The transfer was refused, with one member of the closed union. Nothing was written. */
+export interface CitizenTransferRefused {
+    readonly outcome: 'refused';
+    readonly error: CitizenTransferRefusal;
+}
+/** The ONE declared answer to a Citizen transfer, discriminated by `outcome`. */
+export type CitizenTransferResponse = CitizenTransferMade | CitizenTransferRefused;
+/**
+ * Why a Citizen transfer was refused: CAY-0088 §3's set, closed. A consumer renders a
+ * member by its name. Every member means the same thing about money: nothing moved.
+ */
+export type CitizenTransferRefusal = 
+/**
+ * The verification method is outside the money-grade assurance profile
+ * (`ASSURANCE_POLICY['make-citizen-transfer']`). `dev-bypass` is never inside it.
+ */
+'assurance_not_money_grade'
+/** The verified subject resolves to no Citizen Wallet. A transfer never provisions one. */
+ | 'sender_has_no_citizen_wallet'
+/** No wallet has the payee's id. */
+ | 'payee_wallet_not_found'
+/** The payee's wallet is an Organisation Wallet or the Treasury. Organisations are paid by commercial payment. */
+ | 'payee_wallet_not_a_citizens'
+/** No citizen is bound to the payee's wallet now, for example because the binding was erased. */
+ | 'payee_wallet_has_no_live_binding'
+/** The payee's wallet is the sender's own. */
+ | 'payee_is_the_sender'
+/** The cents are zero, negative or not a whole number. */
+ | 'amount_not_positive_whole_cents'
+/**
+ * The sender's unrestricted cents are short. Restricted cents are never counted and
+ * never drawn (CAY-0074), so a wallet holding enough only once restricted cents are
+ * included is still short.
+ */
+ | 'unrestricted_cents_insufficient'
+/** A holding the transfer would draw is frozen. */
+ | 'cents_frozen'
+/** The key was already used by this sending wallet for a different payee or a different number of cents. */
+ | 'idempotency_key_reused_for_a_different_transfer'
+/** Too many concurrent draws on the sending wallet. Nothing moved; retry under the same key. */
+ | 'carve_contended';

package/dist/citizen-transfer.js

@@ -0,0 +1,16 @@
+/*
+ * Copyright 2026 Percayso Community
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export {};

package/dist/client.d.ts

@@ -70,7 +70,9 @@
 import type { BuyBackMade, BuyBackRequest, CitizenMarketViewed, QuotePlaced, QuoteRequest, QuoteWithdrawalRequest, QuoteWithdrawn } from './citizen-market.js';
 import type { CitizenshipFounderClaimed, CitizenshipView } from './citizenship.js';
 import type { StandingAuthorisationAcknowledged, StandingAuthorisationRequest } from './cloud-settlement.js';
+import type { CitizenTransferMade, CitizenTransferRequest } from './citizen-transfer.js';
 import type { CommercialPaymentMade, CommercialPaymentRequest } from './commercial-payment.js';
+import type { HandleChangeCharged, HandleChangeReceiptReadResponse } from './handle-change.js';
 import type { MarketplaceOrderRequest, MarketplaceOrderSettled } from './marketplace-settlement.js';
 import type { OrganisationView } from './organisation.js';
 import type { PurchaseAuthorised, PurchaseCancelled, PurchaseRequest, PurchaseResult, PurchaseTerminal } from './purchase.js';
@@ -213,6 +215,35 @@ export interface CaysoClient {
      * refusals do. A refusal means nothing moved.
      */
     makeCommercialPayment(req: CommercialPaymentRequest): Promise<CommercialPaymentMade>;
+    /**
+     * Transfer unrestricted cents from the caller's own Citizen Wallet to another
+     * Citizen Wallet — or REPLAY a transfer already made under the same key (CAY-0088).
+     *
+     * The sending wallet is never named: it is the verified holder's own. A replay with
+     * the same key, payee and cents answers the movement already written. A refusal
+     * arrives as a thrown {@link CaysoApiError} whose `code` is a
+     * `CitizenTransferRefusal` member, one of the gate's codes, or a seam code. A
+     * refusal means nothing moved.
+     */
+    makeCitizenTransfer(req: CitizenTransferRequest): Promise<CitizenTransferMade>;
+    /**
+     * Charge the caller's own Citizen Wallet for a Handle change, and receive the signed
+     * receipt Percayso ID relies on (CAY-0091) — or, for a change reference already
+     * charged, the receipt of that charge, with nothing charged again.
+     *
+     * There is nothing to send: the change reference is inside the assertion, the wallet
+     * is the verified holder's own, and the price is Cayso's. A refusal arrives as a thrown
+     * {@link CaysoApiError} whose `code` is a `HandleChangeRefusal` member, one of the
+     * gate's codes, or a seam code. A refusal means nothing moved.
+     */
+    changeHandle(): Promise<HandleChangeCharged>;
+    /**
+     * Ask whether the change reference inside the assertion was charged for the caller
+     * (CAY-0091): its receipt, or `no-charge`. Never "pending". A refusal arrives as a
+     * thrown {@link CaysoApiError} whose `code` is a `HandleChangeReceiptReadRefusal`
+     * member, one of the gate's codes, or a seam code — and is never "no charge".
+     */
+    readHandleChangeReceipt(): Promise<HandleChangeReceiptReadResponse>;
     /**
      * Read the citizen market as the caller sees it (CAY-0080 §1.4): the published
      * value and its band, both bounds per quote unit, the best bid and the best ask with

package/dist/client.js

@@ -221,6 +221,35 @@ function buildClient(options, internals) {
                 idempotencyKey: req.idempotencyKey,
             });
         },
+        async makeCitizenTransfer(req) {
+            return requestJson({
+                method: ROUTES.citizenTransfer.method,
+                path: ROUTES.citizenTransfer.path,
+                // Safe to repeat only because of the key: a repeat replays the transfer.
+                idempotent: typeof req.idempotencyKey === 'string' && req.idempotencyKey.length > 0,
+                body: req,
+                idempotencyKey: req.idempotencyKey,
+            });
+        },
+        async changeHandle() {
+            return requestJson({
+                method: ROUTES.handleChange.method,
+                path: ROUTES.handleChange.path,
+                // Safe to retry with no key: the charge is keyed by the change reference
+                // inside the assertion, so a repeat answers the charge already made, and each
+                // attempt mints a fresh assertion, so the single-use `jti` is never presented
+                // twice.
+                idempotent: true,
+            });
+        },
+        async readHandleChangeReceipt() {
+            return requestJson({
+                method: ROUTES.handleChangeReceipt.method,
+                path: ROUTES.handleChangeReceipt.path,
+                // A read: it moves nothing, so a retry is always safe.
+                idempotent: true,
+            });
+        },
         async getCitizenMarket() {
             return requestJson({
                 method: ROUTES.citizenMarket.method,