@percayso-community/cayso-contracts 0.26.0 → 0.29.0

package/dist/handle-change.d.ts

@@ -0,0 +1,189 @@
+/**
+ * `handle-change` — a Citizen's Handle change, charged by Cayso, and the signed receipt
+ * Percayso ID relies on before it changes the Handle record (CAY-0091).
+ *
+ * Every Handle change after approval is charged in Cayso (Percayso ID's onboarding PRD
+ * §7.2). Cayso holds the price and makes the charge; Percayso ID changes the Handle only
+ * once Cayso has answered with a receipt. Served at `ROUTES.handleChange`, under the
+ * operation `'change-handle'`, and read back at `ROUTES.handleChangeReceipt`, under
+ * `'read-handle-change-receipt'`.
+ *
+ * ## Who calls it
+ *
+ * Percayso ID, over its back channel, as it presents a founder claim. The Citizen
+ * confirms on Percayso ID's own pages; Percayso ID mints a `change-handle` assertion for
+ * that interactive session — never from the background source (CAY-0070) — and presents
+ * it here. The assertion's `sub` is the Citizen ID.
+ *
+ * ## One `charge` for a Community service, or nothing
+ *
+ * The charge is one `charge` movement from the Citizen's own Citizen Wallet to the
+ * Organisation Wallet of the organisation that operates Percayso ID, named in Cayso's
+ * configuration — never a Citizen Wallet (CAY-0084). A Handle change is a Community
+ * service (CAY-0076, as extended by CAY-0091), and a `charge` may draw restricted lots
+ * like any charge, so restricted and unrestricted cents are drawn together. There is no
+ * sterling leg and so no lifecycle: the answer is a {@link HandleChangeCharged} carrying
+ * the signed receipt, or a {@link HandleChangeRefused} meaning nothing moved.
+ *
+ * ## Nothing in the request names anything
+ *
+ * There is no request body. The paying wallet is the verified subject's own Citizen
+ * Wallet, resolved inside the service (CAY-0021). The price is Cayso's configuration.
+ * The change reference — the single-use reference Percayso ID issued when it reserved
+ * the proposed Handle — is carried INSIDE the signed assertion, as
+ * `handleChangeReference`, because a reference named in a body would be the caller's
+ * claim about which Handle change is theirs. Cayso never learns the Handle.
+ *
+ * ## At most one charge per change reference
+ *
+ * The change reference is the charge's key. The first presentation charges; a later
+ * presentation of the same reference for the same Citizen, under a fresh assertion,
+ * charges nothing and answers the receipt of the charge already made — so Percayso ID,
+ * having had no response, retries with the same reference and is answered idempotently.
+ * A reference already charged to another wallet is refused. The same assertion
+ * presented twice never reaches this far: its `jti` is single-use, and the replay is
+ * refused at the gate.
+ *
+ * ## The receipt is a statement Cayso signs
+ *
+ * {@link HandleChangeReceipt} is a {@link HandleChangeReceiptStatement} and an `ES256`
+ * signature over {@link encodeHandleChangeReceiptStatement} of it, made with Cayso's
+ * receipt key (CAY-0083 §1, as amended by CAY-0091) and published in the same key set
+ * as a marketplace receipt's. It is BOUND to the charge: it names the change reference
+ * and the issuer and `jti` of the assertion the charge was made under, which Percayso ID
+ * minted and alone can tie to a Citizen. It names a wallet id and never a Percayso
+ * identity (CAY-0006, CAY-0054): there is no `sub` and no Handle.
+ *
+ * ## Was this reference charged? A receipt or "no charge", never "pending"
+ *
+ * {@link HandleChangeReceiptReadResponse} answers the read Percayso ID makes before it
+ * releases a held Handle: the receipt of the charge the reference landed, or
+ * `no-charge` — nothing was charged under this reference for this Citizen. There is no
+ * `pending`: a movement is written or it is not (CAY-0023). A read writes no row and
+ * moves nothing.
+ *
+ * ## The bytes that are signed, and why they cannot be a marketplace receipt
+ *
+ * {@link encodeHandleChangeReceiptStatement} is the one encoding, called by the signer
+ * and by every verifier: the statement's fields in the order the interface declares
+ * them, as UTF-8 JSON with no whitespace, refusing any field it does not name. Its first
+ * field is `"reason":"handle-change"`, and no marketplace receipt has a `reason` field —
+ * that encoder refuses one — so the one key signing both cannot make either read as the
+ * other.
+ *
+ * ## What is not here
+ *
+ * No figure: the price is a canon figure, configured, and the receipt carries the cents
+ * that moved. No key material and no verifier: which keys Percayso ID trusts is Percayso
+ * ID's configuration, empty by default.
+ */
+import type { MarketplaceReceiptKeyId, MarketplaceReceiptLeg } from './marketplace-receipt.js';
+import type { Millis } from './wallet.js';
+/**
+ * What Cayso signs about one Handle-change charge. Every field is signed, including
+ * `keyId`, so which key signed is part of what is signed.
+ */
+export interface HandleChangeReceiptStatement {
+    /** The reason for the charge. Always the literal, and always first in the encoding. */
+    readonly reason: 'handle-change';
+    /** The act: one `charge`, from the payer to the payee. */
+    readonly movementKind: 'charge';
+    /** The movement that carried the cents. */
+    readonly movementId: string;
+    /** The change reference charged for, exactly as Percayso ID minted it into the assertion. */
+    readonly handleChangeReference: string;
+    /** The issuer of the assertion the charge was made under. */
+    readonly assertionIssuer: string;
+    /** The `jti` of the assertion the charge was made under. */
+    readonly assertionId: string;
+    /** The paying wallet: the Citizen's own Citizen Wallet. */
+    readonly payerWalletId: string;
+    /** The whole price, to the configured Organisation Wallet, as the cents that moved. */
+    readonly payeeLeg: MarketplaceReceiptLeg;
+    /** When the movement was written. */
+    readonly writtenAt: Millis;
+    /** The receipt key the signature was made with. */
+    readonly keyId: MarketplaceReceiptKeyId;
+}
+/** A receipt: the statement, and Cayso's signature over its encoding. */
+export interface HandleChangeReceipt {
+    readonly statement: HandleChangeReceiptStatement;
+    /**
+     * `ES256` over {@link encodeHandleChangeReceiptStatement}`(statement)`: `r || s`, 64
+     * bytes, as unpadded base64url.
+     */
+    readonly signature: string;
+}
+/** The Handle change was charged, by this request or by an earlier one for the same reference. */
+export interface HandleChangeCharged {
+    readonly outcome: 'charged';
+    readonly receipt: HandleChangeReceipt;
+}
+/** The charge was refused, with one member of the closed union. Nothing was written. */
+export interface HandleChangeRefused {
+    readonly outcome: 'refused';
+    readonly error: HandleChangeRefusal;
+}
+/** The ONE declared answer to a Handle change, discriminated by `outcome`. */
+export type HandleChangeResponse = HandleChangeCharged | HandleChangeRefused;
+/**
+ * Why a Handle change was refused: CAY-0091's set, closed. Every member means the same
+ * thing about money: nothing moved.
+ */
+export type HandleChangeRefusal = 
+/**
+ * The verification method is outside the money-grade assurance profile
+ * (`ASSURANCE_POLICY['change-handle']`). `dev-bypass` is never inside it.
+ */
+'assurance_not_money_grade'
+/** The verified subject resolves to no Citizen Wallet. A Handle change never provisions one. */
+ | 'payer_has_no_citizen_wallet'
+/** The payer's cents, restricted and unrestricted together, are short of the price. */
+ | 'cents_insufficient'
+/** A holding the charge would draw is frozen. */
+ | 'cents_frozen'
+/** The change reference has already been charged, to another wallet. */
+ | 'handle_change_reference_charged_to_another_wallet'
+/** Too many concurrent draws on the paying wallet. Nothing moved; retry with the same reference. */
+ | 'carve_contended';
+/** The reference was charged for this Citizen: the receipt of that charge. */
+export interface HandleChangeReceiptFound {
+    readonly outcome: 'receipt';
+    readonly receipt: HandleChangeReceipt;
+}
+/**
+ * Nothing was charged under this reference for this Citizen. Never "pending": there is
+ * no pending charge.
+ */
+export interface HandleChangeNoCharge {
+    readonly outcome: 'no-charge';
+}
+/**
+ * Why the read could not be answered. Closed, and a refusal is never a statement about
+ * the reference: a caller must not read one as "no charge".
+ */
+export type HandleChangeReceiptReadRefusal = 
+/**
+ * No wallet is bound to the verified subject now, so there is no paying wallet to ask
+ * about, and whether the reference was charged is not known.
+ */
+'payer_has_no_citizen_wallet'
+/** The reference was charged, to another wallet. */
+ | 'handle_change_reference_charged_to_another_wallet';
+/** The read was refused, with one reason. Nothing was written. */
+export interface HandleChangeReceiptReadRefused {
+    readonly outcome: 'refused';
+    readonly error: HandleChangeReceiptReadRefusal;
+}
+/** The ONE declared answer to the read: a receipt, "no charge", or a refusal. Never "pending". */
+export type HandleChangeReceiptReadResponse = HandleChangeReceiptFound | HandleChangeNoCharge | HandleChangeReceiptReadRefused;
+/**
+ * The exact bytes a Handle-change receipt's signature is computed over.
+ *
+ * Builds a fresh object from the statement's named fields, in a fixed order, so the
+ * encoding depends on nothing but their values. THROWS a `TypeError` for anything that
+ * is not exactly a {@link HandleChangeReceiptStatement}: a wrong literal, a missing or
+ * extra field, a string field that is not a string, or cents or a time that is not a
+ * safe whole number no less than zero.
+ */
+export declare function encodeHandleChangeReceiptStatement(statement: HandleChangeReceiptStatement): Uint8Array<ArrayBuffer>;

package/dist/handle-change.js

@@ -0,0 +1,96 @@
+/*
+ * 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.
+ */
+// --- The encoding ------------------------------------------------------------
+/** The statement's own fields, in the order they are encoded. */
+const FIELDS = [
+    'reason',
+    'movementKind',
+    'movementId',
+    'handleChangeReference',
+    'assertionIssuer',
+    'assertionId',
+    'payerWalletId',
+    'payeeLeg',
+    'writtenAt',
+    'keyId',
+];
+/** Every string field, each of which must be a string when it arrives. */
+const STRING_FIELDS = [
+    'movementId',
+    'handleChangeReference',
+    'assertionIssuer',
+    'assertionId',
+    'payerWalletId',
+    'keyId',
+];
+/** The fields of a leg, in the order they are encoded. */
+const LEG_FIELDS = ['walletId', 'cents'];
+/**
+ * The exact bytes a Handle-change receipt's signature is computed over.
+ *
+ * Builds a fresh object from the statement's named fields, in a fixed order, so the
+ * encoding depends on nothing but their values. THROWS a `TypeError` for anything that
+ * is not exactly a {@link HandleChangeReceiptStatement}: a wrong literal, a missing or
+ * extra field, a string field that is not a string, or cents or a time that is not a
+ * safe whole number no less than zero.
+ */
+export function encodeHandleChangeReceiptStatement(statement) {
+    const value = statement;
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new TypeError('a Handle-change receipt statement is an object');
+    }
+    requireExactly(value, FIELDS, 'a Handle-change receipt carries exactly its own fields');
+    if (value['reason'] !== 'handle-change' || value['movementKind'] !== 'charge') {
+        throw new TypeError('a Handle-change receipt is for a Handle change made by a charge');
+    }
+    for (const field of STRING_FIELDS) {
+        if (typeof value[field] !== 'string') {
+            throw new TypeError('every identifier of a Handle-change receipt is a string');
+        }
+    }
+    requireWholeNumber(value['writtenAt'], 'a Handle-change receipt is written at whole milliseconds');
+    const canonical = {};
+    for (const field of FIELDS) {
+        canonical[field] = field === 'payeeLeg' ? canonicalLeg(value[field]) : value[field];
+    }
+    return new TextEncoder().encode(JSON.stringify(canonical));
+}
+/** A leg rebuilt in its fixed order, or a refusal. */
+function canonicalLeg(leg) {
+    if (typeof leg !== 'object' || leg === null || Array.isArray(leg)) {
+        throw new TypeError('a Handle-change receipt leg is an object');
+    }
+    const value = leg;
+    requireExactly(value, LEG_FIELDS, 'a Handle-change receipt leg carries a wallet id and cents only');
+    if (typeof value['walletId'] !== 'string') {
+        throw new TypeError('a Handle-change receipt leg names its wallet by id');
+    }
+    requireWholeNumber(value['cents'], 'a Handle-change receipt leg carries whole cents');
+    return { walletId: value['walletId'], cents: value['cents'] };
+}
+/** Refuse an object whose own keys are not exactly `fields`. */
+function requireExactly(value, fields, category) {
+    const keys = Object.keys(value);
+    if (keys.length !== fields.length || !fields.every((field) => Object.hasOwn(value, field))) {
+        throw new TypeError(category);
+    }
+}
+/** Refuse anything that is not a safe whole number no less than zero. */
+function requireWholeNumber(value, category) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new TypeError(category);
+    }
+}

package/dist/index.d.ts

@@ -76,6 +76,45 @@
  * 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.28.0` → `0.29.0` publishes and SERVES the Handle change (CAY-0091):
+ * `ROUTES.handleChange`, `POST /api/handle-changes`, mapped to the new operation
+ * `'change-handle'`, money-grade in `ASSURANCE_POLICY`; `ROUTES.handleChangeReceipt`,
+ * `GET /api/handle-changes/receipt`, mapped to the new read-scope operation
+ * `'read-handle-change-receipt'`; the assertion claim `handleChangeReference`, which
+ * travels with those two operations in both directions; the client methods
+ * `changeHandle` and `readHandleChangeReceipt`; the signed {@link HandleChangeReceipt}
+ * and its one encoding, {@link encodeHandleChangeReceiptStatement}; and
+ * `CaysoApiErrorCode` gains {@link HandleChangeRefusal} and
+ * {@link HandleChangeReceiptReadRefusal} by reference and the seam codes
+ * `handle_change_store_not_configured`, `handle_change_price_not_configured` and
+ * `handle_change_payee_not_configured`. BREAKING in the package's sense because closed
+ * tables grew. Additive on the wire: no route a `0.28.0` consumer calls changed or
+ * answers anything new, and a credential a `0.28.0` issuer mints carries neither the new
+ * scope keys nor the new claim (CAY-0086).
+ *
+ * `0.27.0` → `0.28.0` SERVES a Citizen publisher's marketplace sale (CAY-0090):
+ * `POST /api/marketplace/orders` settles a signed order whose payee is a
+ * `citizen_publisher` as one `marketplace_settlement`, answering the
+ * `MarketplaceSettlementReceiptStatement` `0.24.0` already published. The share is
+ * read from a new signed-order fact, `communityShareBasisPoints`, which Store Platform
+ * signs beside `allocationPolicyVersion`. {@link MarketplaceOrderRefusal} gains
+ * `allocation_share_out_of_range` and `payee_wallet_is_the_buyers`, and
+ * `allocation_policy_version_not_configured` is retired (kept, never answered). The
+ * operator `MovementKind` gains `marketplace_settlement`. BREAKING in the package's
+ * sense because closed tables grew. On the wire, every order a `0.27.0` consumer could
+ * present — one Store Platform signed without the new fact — is answered exactly as
+ * before, a Citizen publisher's with `third_party_marketplace_sale_not_served`; only an
+ * order carrying the new fact can reach a new code (CAY-0086).
+ *
+ * `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 +552,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.29.0";
 /** The package's own name, so a consumer can name what it depends on. */
 export declare const packageName = "@percayso-community/cayso-contracts";
 /**
@@ -647,12 +686,19 @@ export { REQUEST_RATE_LIMITED } from './errors.js';
  * one of the four.
  */
 export { MARKETPLACE_RECEIPT_SIGNATURE_ALGORITHM, encodeMarketplaceReceiptStatement, } from './marketplace-receipt.js';
+/**
+ * The one encoding of a Handle-change receipt statement, called by the signer and by
+ * Percayso ID's verifier (CAY-0091).
+ */
+export { encodeHandleChangeReceiptStatement } from './handle-change.js';
 export type { PositiveCents } from './money.js';
 export type { CaysoApiErrorCode, CaysoErrorResponse } from './errors.js';
 export type { HolderType, Millis, Cents, WalletRecord, Balance, Allowance, WalletView, CaysoWallet, } from './wallet.js';
 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 { HandleChangeReceiptStatement, HandleChangeReceipt, HandleChangeCharged, HandleChangeRefused, HandleChangeResponse, HandleChangeRefusal, HandleChangeReceiptFound, HandleChangeNoCharge, HandleChangeReceiptReadRefusal, HandleChangeReceiptReadRefused, HandleChangeReceiptReadResponse, } from './handle-change.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,45 @@
  * 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.28.0` → `0.29.0` publishes and SERVES the Handle change (CAY-0091):
+ * `ROUTES.handleChange`, `POST /api/handle-changes`, mapped to the new operation
+ * `'change-handle'`, money-grade in `ASSURANCE_POLICY`; `ROUTES.handleChangeReceipt`,
+ * `GET /api/handle-changes/receipt`, mapped to the new read-scope operation
+ * `'read-handle-change-receipt'`; the assertion claim `handleChangeReference`, which
+ * travels with those two operations in both directions; the client methods
+ * `changeHandle` and `readHandleChangeReceipt`; the signed {@link HandleChangeReceipt}
+ * and its one encoding, {@link encodeHandleChangeReceiptStatement}; and
+ * `CaysoApiErrorCode` gains {@link HandleChangeRefusal} and
+ * {@link HandleChangeReceiptReadRefusal} by reference and the seam codes
+ * `handle_change_store_not_configured`, `handle_change_price_not_configured` and
+ * `handle_change_payee_not_configured`. BREAKING in the package's sense because closed
+ * tables grew. Additive on the wire: no route a `0.28.0` consumer calls changed or
+ * answers anything new, and a credential a `0.28.0` issuer mints carries neither the new
+ * scope keys nor the new claim (CAY-0086).
+ *
+ * `0.27.0` → `0.28.0` SERVES a Citizen publisher's marketplace sale (CAY-0090):
+ * `POST /api/marketplace/orders` settles a signed order whose payee is a
+ * `citizen_publisher` as one `marketplace_settlement`, answering the
+ * `MarketplaceSettlementReceiptStatement` `0.24.0` already published. The share is
+ * read from a new signed-order fact, `communityShareBasisPoints`, which Store Platform
+ * signs beside `allocationPolicyVersion`. {@link MarketplaceOrderRefusal} gains
+ * `allocation_share_out_of_range` and `payee_wallet_is_the_buyers`, and
+ * `allocation_policy_version_not_configured` is retired (kept, never answered). The
+ * operator `MovementKind` gains `marketplace_settlement`. BREAKING in the package's
+ * sense because closed tables grew. On the wire, every order a `0.27.0` consumer could
+ * present — one Store Platform signed without the new fact — is answered exactly as
+ * before, a Citizen publisher's with `third_party_marketplace_sale_not_served`; only an
+ * order carrying the new fact can reach a new code (CAY-0086).
+ *
+ * `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 +568,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.29.0';
 /** The package's own name, so a consumer can name what it depends on. */
 export const packageName = '@percayso-community/cayso-contracts';
 /**
@@ -663,3 +702,8 @@ export { REQUEST_RATE_LIMITED } from './errors.js';
  * one of the four.
  */
 export { MARKETPLACE_RECEIPT_SIGNATURE_ALGORITHM, encodeMarketplaceReceiptStatement, } from './marketplace-receipt.js';
+/**
+ * The one encoding of a Handle-change receipt statement, called by the signer and by
+ * Percayso ID's verifier (CAY-0091).
+ */
+export { encodeHandleChangeReceiptStatement } from './handle-change.js';

package/dist/marketplace-settlement.d.ts

@@ -12,8 +12,10 @@
  *
  * **This is the contract surface only.** Nothing here settles anything. Since
  * `0.24.0` a route serves `settle-marketplace-order` for a house-publisher sale
- * (`ROUTES.marketplaceOrder`); the third-party sale and the refund are not served. The sale table, the registry of Store Platform order
- * keys and the ledger stay in this proprietary tree (CAY-0083 §3).
+ * (`ROUTES.marketplaceOrder`), and since `0.28.0` for a Citizen publisher's sale too,
+ * as one `marketplace_settlement` with a publisher leg and a Community leg (CAY-0090).
+ * The refund is not served, for either kind of sale. The sale table, the registry of
+ * Store Platform order keys and the ledger stay in this proprietary tree (CAY-0083 §3).
  *
  * ## Two operations, because two authorities are checked
  *
@@ -41,7 +43,9 @@
  * disagree eventually. What Cayso reads from them, once verified, is CAY-0082's
  * list — the order digest, the checkout's idempotency key, the price, the paying
  * wallet, the payee wallet or the house-publisher fact, and the allocation-policy
- * version.
+ * version — and, since `0.28.0`, the Community's share in basis points, which Store
+ * Platform snapshots into the checkout from its allocation policy and signs beside the
+ * version (CAY-0090, amending CAY-0082 §3).
  *
  * **Nothing about the sale is taken from the caller's word.** The house-publisher
  * fact, the payee wallet, the price and the idempotency key are all inside the
@@ -198,17 +202,33 @@ export type MarketplaceOrderRefusal =
  */
  | 'idempotency_key_reused_for_a_different_order'
 /**
- * The allocation-policy version the order names has no figure configured here, so
- * a third-party sale's split cannot be computed. A closed door, never a default
- * split. A house-publisher sale has no split and never meets it.
+ * RETIRED in `0.28.0`, and never answered since. It was published for a Cayso that
+ * would hold each allocation-policy version's figure itself; CAY-0090 put the figure
+ * in Store Platform's signed order instead, so no version can be "not configured"
+ * here. Kept in the union so a consumer's exhaustive map keeps compiling; a consumer
+ * may stop rendering it.
  */
  | 'allocation_policy_version_not_configured'
+/**
+ * The Community's share the signed order carries (`communityShareBasisPoints`) is not
+ * a whole number from 0 to 10000, or, for a Citizen publisher's sale, leaves the
+ * publisher leg or the Community leg at zero cents at this price. A leg is a lot that
+ * arrives, and a lot of no cents is not one (CAY-0078, CAY-0090), so a share of 0 or
+ * 10000, or a price too small to split, is refused rather than settled with one leg.
+ */
+ | 'allocation_share_out_of_range'
 /** No wallet has the payee's id. */
  | 'payee_wallet_not_found'
 /** The payee's wallet is an Organisation Wallet or the Treasury. A paid sale's publisher is a Citizen (CAY-0082 §8). */
  | '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 buyer's own: a publisher buying their own listing. A
+ * movement never runs from a wallet to itself, so nothing is paid and nothing is
+ * written (CAY-0090).
+ */
+ | 'payee_wallet_is_the_buyers'
 /**
  * A third-party sale: the buyer's unrestricted cents are short. Restricted cents
  * are never counted and never drawn for one (CAY-0076), so a wallet holding enough

package/dist/operator.d.ts

@@ -85,7 +85,7 @@ export declare const OPERATOR_READ_ROUTES: {
  * movement list's `kind` filter refuses anything outside it (`400 invalid_kind`), and
  * every row's `kind` is one of these.
  */
-export type MovementKind = 'issuance' | 'purchase' | 'grant' | 'charge' | 'payout' | 'transfer' | 'burn' | 'forfeit' | 'commercial_payment' | 'quoted_sale' | 'buy_back' | 'quoted_sale_compensation';
+export type MovementKind = 'issuance' | 'purchase' | 'grant' | 'charge' | 'payout' | 'transfer' | 'burn' | 'forfeit' | 'commercial_payment' | 'quoted_sale' | 'buy_back' | 'quoted_sale_compensation' | 'marketplace_settlement';
 /** Every {@link MovementKind}, in the service's order — for a filter a person picks from. */
 export declare const MOVEMENT_KINDS: readonly MovementKind[];
 /**
@@ -96,6 +96,11 @@ export declare const MOVEMENT_KINDS: readonly MovementKind[];
  * `fromWalletId` is null when the cents came from unissued (an issuance) and
  * `toWalletId` is null when they went back to it (a burn, a forfeiture). Both are
  * wallet ids — the operator-facing handle — and never an identity.
+ *
+ * A `marketplace_settlement` lands in two wallets (CAY-0082 §1): `toWalletId` is the
+ * publisher's Citizen Wallet and `cents` the whole price the buyer paid. The Community
+ * leg's share of it went to the Treasury inside the same movement, and the row does not
+ * itemise it; the signed receipt names both legs (CAY-0090).
  */
 export interface OperatorMovementRow {
     /** The row's own opaque handle: a stable list key, not an identity. */

package/dist/operator.js

@@ -45,4 +45,5 @@ export const MOVEMENT_KINDS = [
     'quoted_sale',
     'buy_back',
     'quoted_sale_compensation',
+    'marketplace_settlement',
 ];

package/dist/routes.d.ts

@@ -76,6 +76,24 @@
  * (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 `handleChange` and `handleChangeReceipt` take nothing but the credential
+ *
+ * `POST /api/handle-changes` is a Citizen's Handle change, charged by Cayso, and
+ * `GET /api/handle-changes/receipt` asks whether a change reference was charged
+ * (CAY-0091). Nothing either request could carry is the caller's to say: the paying
+ * wallet is the verified subject's own, the price is Cayso's configuration, and the
+ * change reference is inside the signed assertion. So there is nothing to send but the
+ * credential, as with the founder claim. They are two paths because they are two
+ * operations, and one path carries one scope requirement at the gate.
+ *
  * ## 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 +164,18 @@ export declare const ROUTES: {
         readonly method: "POST";
         readonly path: "/api/commercial-payments";
     };
+    readonly citizenTransfer: {
+        readonly method: "POST";
+        readonly path: "/api/citizen-transfers";
+    };
+    readonly handleChange: {
+        readonly method: "POST";
+        readonly path: "/api/handle-changes";
+    };
+    readonly handleChangeReceipt: {
+        readonly method: "GET";
+        readonly path: "/api/handle-changes/receipt";
+    };
     readonly citizenMarket: {
         readonly method: "GET";
         readonly path: "/api/citizen-market";

package/dist/routes.js

@@ -91,6 +91,24 @@
  * (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 `handleChange` and `handleChangeReceipt` take nothing but the credential
+ *
+ * `POST /api/handle-changes` is a Citizen's Handle change, charged by Cayso, and
+ * `GET /api/handle-changes/receipt` asks whether a change reference was charged
+ * (CAY-0091). Nothing either request could carry is the caller's to say: the paying
+ * wallet is the verified subject's own, the price is Cayso's configuration, and the
+ * change reference is inside the signed assertion. So there is nothing to send but the
+ * credential, as with the founder claim. They are two paths because they are two
+ * operations, and one path carries one scope requirement at the gate.
+ *
  * ## 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 +152,9 @@ 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' },
+    handleChange: { method: 'POST', path: '/api/handle-changes' },
+    handleChangeReceipt: { method: 'GET', path: '/api/handle-changes/receipt' },
     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.29.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": {