@percayso-community/cayso-contracts 0.26.0 → 0.27.0

package/dist/assertion.d.ts

@@ -319,6 +319,13 @@
  * 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`.
+ *
  * `'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 +370,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' | '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

package/dist/assurance.js

@@ -325,6 +325,24 @@ 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.',
+    },
     // 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 +523,7 @@ export const OPERATION_FOR_ROUTE = {
     purchaseResult: 'read-purchase-result',
     purchaseCancel: 'cancel-purchase',
     commercialPayment: 'make-commercial-payment',
+    citizenTransfer: 'make-citizen-transfer',
     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,6 +70,7 @@
 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 { MarketplaceOrderRequest, MarketplaceOrderSettled } from './marketplace-settlement.js';
 import type { OrganisationView } from './organisation.js';
@@ -213,6 +214,17 @@ 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>;
     /**
      * 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,16 @@ 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 getCitizenMarket() {
             return requestJson({
                 method: ROUTES.citizenMarket.method,

package/dist/contract-schema.generated.js

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 export const CONTRACT_SCHEMA = {
-    "contractVersion": "0.26.0",
+    "contractVersion": "0.27.0",
     "packageName": "@percayso-community/cayso-contracts",
     "capabilities": {
         "wallet": "cayso.wallet",
@@ -57,6 +57,10 @@ export const CONTRACT_SCHEMA = {
             "method": "POST",
             "path": "/api/commercial-payments"
         },
+        "citizenTransfer": {
+            "method": "POST",
+            "path": "/api/citizen-transfers"
+        },
         "citizenMarket": {
             "method": "GET",
             "path": "/api/citizen-market"
@@ -654,6 +658,9 @@ export const CONTRACT_SCHEMA = {
                     {
                         "literal": "commercial_payment_store_not_configured"
                     },
+                    {
+                        "literal": "citizen_transfer_store_not_configured"
+                    },
                     {
                         "literal": "citizen_market_not_configured"
                     },
@@ -696,6 +703,9 @@ export const CONTRACT_SCHEMA = {
                     {
                         "ref": "CommercialPaymentRefusal"
                     },
+                    {
+                        "ref": "CitizenTransferRefusal"
+                    },
                     {
                         "ref": "QuotePlacementRefusal"
                     },
@@ -893,6 +903,163 @@ export const CONTRACT_SCHEMA = {
                 }
             }
         },
+        "CitizenTransfer": {
+            "kind": "object",
+            "properties": {
+                "movementId": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "fromWalletId": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "payeeWalletId": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "cents": {
+                    "type": {
+                        "ref": "Cents"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "transferredAt": {
+                    "type": {
+                        "ref": "Millis"
+                    },
+                    "readonly": true,
+                    "optional": false
+                }
+            }
+        },
+        "CitizenTransferMade": {
+            "kind": "object",
+            "properties": {
+                "outcome": {
+                    "type": {
+                        "literal": "transferred"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "transfer": {
+                    "type": {
+                        "ref": "CitizenTransfer"
+                    },
+                    "readonly": true,
+                    "optional": false
+                }
+            }
+        },
+        "CitizenTransferRefusal": {
+            "kind": "alias",
+            "of": {
+                "union": [
+                    {
+                        "literal": "assurance_not_money_grade"
+                    },
+                    {
+                        "literal": "sender_has_no_citizen_wallet"
+                    },
+                    {
+                        "literal": "payee_wallet_not_found"
+                    },
+                    {
+                        "literal": "payee_wallet_not_a_citizens"
+                    },
+                    {
+                        "literal": "payee_wallet_has_no_live_binding"
+                    },
+                    {
+                        "literal": "payee_is_the_sender"
+                    },
+                    {
+                        "literal": "amount_not_positive_whole_cents"
+                    },
+                    {
+                        "literal": "unrestricted_cents_insufficient"
+                    },
+                    {
+                        "literal": "cents_frozen"
+                    },
+                    {
+                        "literal": "idempotency_key_reused_for_a_different_transfer"
+                    },
+                    {
+                        "literal": "carve_contended"
+                    }
+                ]
+            }
+        },
+        "CitizenTransferRefused": {
+            "kind": "object",
+            "properties": {
+                "outcome": {
+                    "type": {
+                        "literal": "refused"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "error": {
+                    "type": {
+                        "ref": "CitizenTransferRefusal"
+                    },
+                    "readonly": true,
+                    "optional": false
+                }
+            }
+        },
+        "CitizenTransferRequest": {
+            "kind": "object",
+            "properties": {
+                "payeeWalletId": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "cents": {
+                    "type": {
+                        "ref": "Cents"
+                    },
+                    "readonly": true,
+                    "optional": false
+                },
+                "idempotencyKey": {
+                    "type": {
+                        "scalar": "string"
+                    },
+                    "readonly": true,
+                    "optional": false
+                }
+            }
+        },
+        "CitizenTransferResponse": {
+            "kind": "alias",
+            "of": {
+                "union": [
+                    {
+                        "ref": "CitizenTransferMade"
+                    },
+                    {
+                        "ref": "CitizenTransferRefused"
+                    }
+                ]
+            }
+        },
         "Citizenship": {
             "kind": "alias",
             "of": {
@@ -1329,6 +1496,9 @@ export const CONTRACT_SCHEMA = {
                     {
                         "literal": "make-commercial-payment"
                     },
+                    {
+                        "literal": "make-citizen-transfer"
+                    },
                     {
                         "literal": "place-quote"
                     },

package/dist/errors.d.ts

@@ -44,6 +44,7 @@
 import type { FounderClaimRefusal } from './citizenship.js';
 import type { BuyBackRefusal, QuotePlacementRefusal, QuoteWithdrawalRefusal } from './citizen-market.js';
 import type { SettlementAssertionRefusal, StandingAuthorisationRefusal } from './cloud-settlement.js';
+import type { CitizenTransferRefusal } from './citizen-transfer.js';
 import type { CommercialPaymentRefusal } from './commercial-payment.js';
 import type { MarketplaceReceiptReadRefusal } from './marketplace-receipt.js';
 import type { MarketplaceOrderRefusal, MarketplaceRefundRefusal } from './marketplace-settlement.js';
@@ -119,6 +120,12 @@ export type CaysoApiErrorCode =
  * (CAY-0079 §3).
  */
  | 'commercial_payment_store_not_configured'
+/**
+ * No Citizen transfer store is wired, so the route is closed (CAY-0088 §3). It
+ * describes the deployment and not the transfer, so it is not a member of the
+ * transfer's refusal union.
+ */
+ | 'citizen_transfer_store_not_configured'
 /**
  * The citizen market is shut on this deployment: no store is wired, or a figure
  * the book needs is not set in the canon and so not configured here (CAY-0080,
@@ -176,7 +183,7 @@ export type CaysoApiErrorCode =
 /** There is no such purchase under this caller's wallet. */
  | 'not_found'
 /** Something failed on the way and the refusal discloses nothing further. */
- | 'internal_error' | PurchaseFailureReason | PurchaseCancelRefusalReason | FounderClaimRefusal | CommercialPaymentRefusal | QuotePlacementRefusal | QuoteWithdrawalRefusal | BuyBackRefusal | MarketplaceReceiptReadRefusal | MarketplaceOrderRefusal | MarketplaceRefundRefusal | StandingAuthorisationRefusal | SettlementAssertionRefusal;
+ | 'internal_error' | PurchaseFailureReason | PurchaseCancelRefusalReason | FounderClaimRefusal | CommercialPaymentRefusal | CitizenTransferRefusal | QuotePlacementRefusal | QuoteWithdrawalRefusal | BuyBackRefusal | MarketplaceReceiptReadRefusal | MarketplaceOrderRefusal | MarketplaceRefundRefusal | StandingAuthorisationRefusal | SettlementAssertionRefusal;
 /**
  * The body of every refusal on this surface: one code, and nothing beside it.
  *

package/dist/index.d.ts

@@ -76,6 +76,15 @@
  * this money surface gains that Piper's own contracts lack, since theirs share
  * one global version bumped across all twenty-two together (CAY-0026).
  *
+ * `0.26.0` → `0.27.0` publishes and SERVES the Citizen transfer (CAY-0088):
+ * `ROUTES.citizenTransfer`, `POST /api/citizen-transfers`, mapped to the new
+ * operation `'make-citizen-transfer'`, money-grade in `ASSURANCE_POLICY`; the client
+ * method `makeCitizenTransfer`; and `CaysoApiErrorCode` gains
+ * {@link CitizenTransferRefusal} by reference and the seam code
+ * `citizen_transfer_store_not_configured`. It is BREAKING in the package's sense
+ * because three closed tables grew. It is additive on the wire: no route a `0.26.0`
+ * consumer calls changed or answers anything new (CAY-0086).
+ *
  * `0.25.0` → `0.26.0` publishes the operator read surface on its own entry point,
  * `@percayso-community/cayso-contracts/operator` (CAY-0026 Amendment 4), and describes
  * it in the schema under `operator`: the movement list, the purchase list and the
@@ -513,7 +522,7 @@
  * have needed a breaking bump on their own. Under semver below `1.0.0` the minor
  * is where a breaking change goes, so the minor moves and the patch does not.
  */
-export declare const CONTRACT_VERSION: "0.26.0";
+export declare const CONTRACT_VERSION: "0.27.0";
 /** The package's own name, so a consumer can name what it depends on. */
 export declare const packageName = "@percayso-community/cayso-contracts";
 /**
@@ -653,6 +662,7 @@ export type { HolderType, Millis, Cents, WalletRecord, Balance, Allowance, Walle
 export type { SignUpGrantTerms, SignUpGrant, CitizenshipNotProvisioned, CitizenshipProvisioned, CitizenshipFounderClaimed, Citizenship, CitizenshipView, FounderClaimRefusal, } from './citizenship.js';
 export type { OrganisationView } from './organisation.js';
 export type { CommercialPaymentAuthority, CommercialPaymentRequest, CommercialPayment, CommercialPaymentMade, CommercialPaymentRefused, CommercialPaymentResponse, CommercialPaymentRefusal, } from './commercial-payment.js';
+export type { CitizenTransferRequest, CitizenTransfer, CitizenTransferMade, CitizenTransferRefused, CitizenTransferResponse, CitizenTransferRefusal, } from './citizen-transfer.js';
 export type { QuoteSide, QuoteRequest, Quote, QuotePlaced, QuoteRefused, QuoteResponse, QuoteEntryRefusal, QuotePlacementRefusal, QuoteWithdrawalRequest, QuoteWithdrawal, QuoteWithdrawn, QuoteWithdrawalRefused, QuoteWithdrawalResponse, QuoteWithdrawalRefusal, BuyBackRequest, BuyBack, BuyBackMade, BuyBackRefused, BuyBackResponse, BuyBackRefusal, BookLevel, QuoteStatus, QuoteWithdrawalReason, OwnQuote, OwnQuoteNotWithdrawn, OwnQuoteWithdrawn, CitizenMarketView, CitizenMarketViewed, CitizenMarketViewRefusal, CitizenMarketViewRefused, CitizenMarketResponse, } from './citizen-market.js';
 export type { MarketplaceReceiptSignatureAlgorithm, MarketplaceReceiptKeyId, MarketplaceSaleKind, MarketplaceReceiptLeg, MarketplaceSettlementReceiptStatement, HousePublisherChargeReceiptStatement, ThirdPartyRefundReceiptStatement, HousePublisherRefundReceiptStatement, MarketplaceReceiptStatement, MarketplaceReceipt, MarketplaceReceiptReadRequest, MarketplaceReceiptFound, MarketplaceNoMovement, MarketplaceReceiptReadRefusal, MarketplaceReceiptReadRefused, MarketplaceReceiptReadResponse, } from './marketplace-receipt.js';
 export type { StoreSignedStatement, MarketplaceOrderRequest, MarketplaceRefundRequest, MarketplaceOrderReceipt, MarketplaceRefundReceipt, MarketplaceOrderSettled, MarketplaceOrderRefused, MarketplaceOrderResponse, MarketplaceOrderRefusal, MarketplaceRefundSettled, MarketplaceRefundRefused, MarketplaceRefundResponse, MarketplaceRefundRefusal, } from './marketplace-settlement.js';

package/dist/index.js

@@ -92,6 +92,15 @@
  * this money surface gains that Piper's own contracts lack, since theirs share
  * one global version bumped across all twenty-two together (CAY-0026).
  *
+ * `0.26.0` → `0.27.0` publishes and SERVES the Citizen transfer (CAY-0088):
+ * `ROUTES.citizenTransfer`, `POST /api/citizen-transfers`, mapped to the new
+ * operation `'make-citizen-transfer'`, money-grade in `ASSURANCE_POLICY`; the client
+ * method `makeCitizenTransfer`; and `CaysoApiErrorCode` gains
+ * {@link CitizenTransferRefusal} by reference and the seam code
+ * `citizen_transfer_store_not_configured`. It is BREAKING in the package's sense
+ * because three closed tables grew. It is additive on the wire: no route a `0.26.0`
+ * consumer calls changed or answers anything new (CAY-0086).
+ *
  * `0.25.0` → `0.26.0` publishes the operator read surface on its own entry point,
  * `@percayso-community/cayso-contracts/operator` (CAY-0026 Amendment 4), and describes
  * it in the schema under `operator`: the movement list, the purchase list and the
@@ -529,7 +538,7 @@
  * have needed a breaking bump on their own. Under semver below `1.0.0` the minor
  * is where a breaking change goes, so the minor moves and the patch does not.
  */
-export const CONTRACT_VERSION = '0.26.0';
+export const CONTRACT_VERSION = '0.27.0';
 /** The package's own name, so a consumer can name what it depends on. */
 export const packageName = '@percayso-community/cayso-contracts';
 /**

package/dist/routes.d.ts

@@ -76,6 +76,14 @@
  * (CAY-0079 §2). A path that took a payee's identity would make this route a
  * directory of identities for anyone holding a mandate.
  *
+ * ## Why `citizenTransfer` names only the payee, and never the sender
+ *
+ * `POST /api/citizen-transfers` is a Citizen transferring Cayso to another Citizen
+ * (CAY-0088). The body carries the payee's wallet id, the cents and the key. The
+ * sending wallet is NOT in the request: it is the verified subject's own Citizen
+ * Wallet, resolved inside `apps/api`, because a sending wallet the caller named would
+ * be the caller's claim about whose cents these are (CAY-0021).
+ *
  * ## Why the citizen market is FOUR PATHS, and none of them names a wallet
  *
  * `citizenMarket` reads the book, `placeQuote` places a quote, and `withdrawQuote`
@@ -146,6 +154,10 @@ export declare const ROUTES: {
         readonly method: "POST";
         readonly path: "/api/commercial-payments";
     };
+    readonly citizenTransfer: {
+        readonly method: "POST";
+        readonly path: "/api/citizen-transfers";
+    };
     readonly citizenMarket: {
         readonly method: "GET";
         readonly path: "/api/citizen-market";

package/dist/routes.js

@@ -91,6 +91,14 @@
  * (CAY-0079 §2). A path that took a payee's identity would make this route a
  * directory of identities for anyone holding a mandate.
  *
+ * ## Why `citizenTransfer` names only the payee, and never the sender
+ *
+ * `POST /api/citizen-transfers` is a Citizen transferring Cayso to another Citizen
+ * (CAY-0088). The body carries the payee's wallet id, the cents and the key. The
+ * sending wallet is NOT in the request: it is the verified subject's own Citizen
+ * Wallet, resolved inside `apps/api`, because a sending wallet the caller named would
+ * be the caller's claim about whose cents these are (CAY-0021).
+ *
  * ## Why the citizen market is FOUR PATHS, and none of them names a wallet
  *
  * `citizenMarket` reads the book, `placeQuote` places a quote, and `withdrawQuote`
@@ -134,6 +142,7 @@ export const ROUTES = {
     purchaseResult: { method: 'GET', path: '/api/purchases/:purchaseId' },
     purchaseCancel: { method: 'POST', path: '/api/purchases/:purchaseId/cancel' },
     commercialPayment: { method: 'POST', path: '/api/commercial-payments' },
+    citizenTransfer: { method: 'POST', path: '/api/citizen-transfers' },
     citizenMarket: { method: 'GET', path: '/api/citizen-market' },
     placeQuote: { method: 'POST', path: '/api/quotes' },
     withdrawQuote: { method: 'POST', path: '/api/quote-withdrawals' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percayso-community/cayso-contracts",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "The versioned capability contract surface through which anything outside this repository reads a wallet. Published; keep it the surface of every consumer outside this tree, Piper and the Percayso Cloud, and nothing internal.",
   "license": "Apache-2.0",
   "repository": {