@percayso-community/cayso-contracts 0.27.0 → 0.30.0

package/dist/index.js

@@ -92,6 +92,94 @@
  * 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.29.0` → `0.30.0` publishes and SERVES Cayso's authorisation acknowledgement keys
+ * (CAY-0093): {@link ACKNOWLEDGEMENT_KEYS_ROUTE}, `GET /api/acknowledgement-keys`, an
+ * unauthenticated read outside `ROUTES`, described in the schema under `keyRoutes`;
+ * the key set it answers, {@link AcknowledgementKeySet} of
+ * {@link AcknowledgementPublicKey}, Ed25519 public JSON Web Keys and nothing private;
+ * and `CaysoApiErrorCode` gains `acknowledgement_signing_not_configured`, the route's
+ * closed door.
+ *
+ * The same version SERVES the standing authorisation (CAY-0094), published at `0.25.0`
+ * and answered until now by the router's `404`: `ROUTES.standingAuthorisation` answers
+ * {@link StandingAuthorisationResponse} with an acknowledgement signed under that key.
+ * It adds the owner's way to withdraw one: `ROUTES.revokeStandingAuthorisation`,
+ * `POST /api/cloud/standing-authorisation-revocations`, mapped to the new operation
+ * `'revoke-standing-authorisation'`, money-grade in `ASSURANCE_POLICY`; the client
+ * method `revokeStandingAuthorisation`; {@link StandingAuthorisationRevocationRequest},
+ * {@link StandingAuthorisationRevocationResponse} and the closed
+ * {@link StandingAuthorisationRevocationRefusal}, which `CaysoApiErrorCode` gains by
+ * reference; and the seam codes `standing_authorisation_store_not_configured`,
+ * `standing_authorisation_cap_ceiling_not_configured` and
+ * `standing_authorisation_life_ceiling_not_configured`.
+ *
+ * The same version publishes and SERVES binding a Node to a wallet (CMTY-0018 §4,
+ * CAY-0095): `ROUTES.bindNode`, `POST /api/cloud/node-bindings`, mapped to the new
+ * operation `'bind-node'`, money-grade in `ASSURANCE_POLICY`; the client method
+ * `bindNode`; {@link NodePresentationClaims}, {@link NodeBindingRequest},
+ * {@link NodeBindingResponse} and the closed {@link NodeBindingRefusal}. Beside it, the
+ * Contribution Store's read of whether a Node is bound: {@link NODE_BINDING_QUERY_ROUTE},
+ * `POST /api/cloud/node-binding-queries`, outside `ROUTES` and in the schema under
+ * `issuerRoutes`, authenticated by the registered Store issuer; {@link
+ * NodeBindingQueryClaims}, {@link NodeBindingQueryRequest}, the answer
+ * {@link NodeBindingStatus} — `nodeId` and `bound` and nothing else — and the closed
+ * {@link NodeBindingQueryRefusal}. `CaysoApiErrorCode` gains both unions by reference
+ * and the seam codes `node_binding_store_not_configured`, `core_node_ids_not_configured`
+ * and `contribution_store_issuer_not_configured`.
+ *
+ * The same version SERVES the Contribution Store's settlement assertion (CMTY-0018 §2,
+ * CAY-0096) at {@link CLOUD_SETTLEMENT_ROUTE}, published at `0.25.0` and answered until
+ * now by the router's `404`. A settled period writes one `contribution_settlement`
+ * movement per paid contribution row and one `consumption_settlement` per consumption
+ * row, so `MovementKind` and `MOVEMENT_KINDS` gain both. The closed refusal unions gain
+ * the members the write needs: {@link SettlementAssertionLevelRefusal} gains
+ * `settlement_period_not_recognised`, `settlement_period_not_ended` and
+ * `settlement_carve_contended`; {@link ContributionRowRefusal} gains
+ * `contribution_node_is_a_core_node` and `contribution_treasury_short`;
+ * {@link ConsumptionRowRefusal} gains `consumption_authorisation_not_in_force` and
+ * `consumption_wallet_short`. `CaysoApiErrorCode` gains them by reference and the seam
+ * code `cloud_settlement_store_not_configured`.
+ *
+ * BREAKING in the package's sense because closed tables grew: `ROUTES`,
+ * `ContractOperation`, `CaysoApiErrorCode`, `MovementKind` and the settlement's refusal
+ * unions. Additive on the wire (CAY-0086): no route a `0.29.0` consumer could reach
+ * changed, because the only ones that answer differently are the standing
+ * authorisation and the settlement assertion, which no deployment served before, and
+ * they answer the shapes `0.25.0` published, a member those shapes' unions gained, or a
+ * new seam code no served route emits. The operator movement list can now carry the two
+ * new kinds, and it is read only by the admin app in this tree, released with it. The
+ * two Node routes are ones a `0.29.0` consumer cannot name.
+ *
+ * `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
@@ -538,7 +626,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.27.0';
+export const CONTRACT_VERSION = '0.30.0';
 /** The package's own name, so a consumer can name what it depends on. */
 export const packageName = '@percayso-community/cayso-contracts';
 /**
@@ -562,6 +650,18 @@ export { ROUTES } from './routes.js';
  * no operation, no assurance bar and no client method.
  */
 export { CLOUD_SETTLEMENT_ROUTE } from './routes.js';
+/**
+ * Where the Contribution Store asks whether a Node is bound (CAY-0095). A value beside
+ * `ROUTES` and never in it, for the settlement path's reason: it is authenticated by
+ * the registered Store issuer, not by a person.
+ */
+export { NODE_BINDING_QUERY_ROUTE } from './routes.js';
+/**
+ * Where Cayso publishes its authorisation acknowledgement keys (CAY-0093). A value
+ * beside `ROUTES` and never in it: an unauthenticated read of a public key carries no
+ * identity, so it has no operation, no assurance bar and no client method.
+ */
+export { ACKNOWLEDGEMENT_KEYS_ROUTE } from './routes.js';
 /**
  * The purchase lifecycle's runtime half (CAY-0032): which statuses a purchase
  * never leaves, the predicate over them, and the window an authorisation holds its
@@ -672,3 +772,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' | 'contribution_settlement' | 'consumption_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,16 @@ 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).
+ *
+ * A `contribution_settlement` runs from the Treasury to a Node's wallet, and a
+ * `consumption_settlement` from an Instance's wallet to the Treasury: one per row of a
+ * settled Cloud period (CAY-0096). Neither row names the Node, the authorisation or
+ * the period; the wallet ids are the handle here as everywhere.
  */
 export interface OperatorMovementRow {
     /** The row's own opaque handle: a stable list key, not an identity. */

package/dist/operator.js

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

package/dist/routes.d.ts

@@ -84,6 +84,16 @@
  * 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`
@@ -109,13 +119,34 @@
  * authorisation under the owner's assertion (`present-standing-authorisation`,
  * CMTY-0018 §1). A person is behind it, so it is classified by a person's
  * assurance like every other entry. It names no wallet: the wallet is the verified
- * holder's own. It is published before it is served.
+ * holder's own. Published at `0.25.0` and served from `0.30.0` (CAY-0094).
+ *
+ * `revokeStandingAuthorisation` withdraws one (`revoke-standing-authorisation`). It
+ * is its own path for citizenship's reason, and a `POST` for cancelling's: nothing is
+ * deleted. The authorisation's row stays, and so does its Instance key's binding to
+ * the wallet; the revocation is a row of its own beside them. The body names the
+ * authorisation's `jti` and no wallet.
+ *
+ * `bindNode` binds a Node to the wallet its presenting Instance key is already bound
+ * to (`bind-node`, CAY-0095), under the owner's assertion. A person is behind it, so
+ * it is classified by a person's assurance. The body carries the Node ID signed by the
+ * Instance key and that key's public half, and no wallet: the wallet is the one the
+ * key is bound to, which must be the verified holder's own. A `POST` to a collection
+ * of bindings, because a Node is bound once and a repeat answers the same.
  *
  * The Contribution Store's settlement assertion is presented by no person. Its path
  * is {@link CLOUD_SETTLEMENT_ROUTE}, outside this table, because every entry here is
  * mapped in `OPERATION_FOR_ROUTE` to the assurance a person needs, and `null` there
  * means "carries no identity", which is false of an assertion a registered issuer
- * signed.
+ * signed. The Store's read of whether a Node is bound,
+ * {@link NODE_BINDING_QUERY_ROUTE}, is outside it for the same reason.
+ *
+ * ## Why Cayso's acknowledgement keys are outside this table too
+ *
+ * {@link ACKNOWLEDGEMENT_KEYS_ROUTE} publishes the public half of the key Cayso signs
+ * an authorisation acknowledgement with. It carries no identity at all, so it is not
+ * a person's operation either, and it is read by the Percayso Cloud's software rather
+ * than by a person's, so the client has no method for it.
  */
 export declare const ROUTES: {
     readonly wallet: {
@@ -158,6 +189,14 @@ export declare const ROUTES: {
         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";
@@ -182,6 +221,14 @@ export declare const ROUTES: {
         readonly method: "POST";
         readonly path: "/api/cloud/standing-authorisations";
     };
+    readonly revokeStandingAuthorisation: {
+        readonly method: "POST";
+        readonly path: "/api/cloud/standing-authorisation-revocations";
+    };
+    readonly bindNode: {
+        readonly method: "POST";
+        readonly path: "/api/cloud/node-bindings";
+    };
     readonly version: {
         readonly method: "GET";
         readonly path: "/api/version";
@@ -199,9 +246,45 @@ export declare const ROUTES: {
  * in {@link ROUTES}, whose every entry is classified by a person's assurance. The
  * client has no method for it, because no person's software calls it.
  *
- * Published before it is served.
+ * Published at `0.25.0` and served from `0.30.0` (CAY-0096): a settled period is one
+ * `contribution_settlement` movement per paid contribution row and one
+ * `consumption_settlement` movement per consumption row, written whole or not at all.
  */
 export declare const CLOUD_SETTLEMENT_ROUTE: {
     readonly method: "POST";
     readonly path: "/api/cloud/settlement-assertions";
 };
+/**
+ * Where the Percayso Cloud's Contribution Store asks whether one Node is bound to a
+ * wallet (CMTY-0018 §4, CAY-0095), so it can carry an unbound Node's rows withheld
+ * (`node_not_bound`) rather than pay them to nobody.
+ *
+ * **Authenticated by the registered Store issuer, exactly as
+ * {@link CLOUD_SETTLEMENT_ROUTE} is, and never by a person.** The body is the Store's
+ * own signed query, naming the one Node it asks about, so a captured query answers
+ * for that Node and no other. A person issuer's key is never the Store's, so a query
+ * a person signed is refused. It answers `{ nodeId, bound }` and nothing else: no
+ * wallet, holder, Citizen or date crosses to the Cloud. A `POST` because the question
+ * travels signed in the body; nothing is written. Not in {@link ROUTES}, and no
+ * client method, because no person's software calls it.
+ */
+export declare const NODE_BINDING_QUERY_ROUTE: {
+    readonly method: "POST";
+    readonly path: "/api/cloud/node-binding-queries";
+};
+/**
+ * Where Cayso publishes the public half of every key it signs an authorisation
+ * acknowledgement with (CMTY-0018 §1, CMTY-0022 row 9): a JSON Web Key Set the
+ * Percayso Cloud reads to verify an acknowledgement an Instance hands it.
+ *
+ * **An unauthenticated read**, because a public key is public: it carries no
+ * identity, names no wallet and moves nothing. Not in {@link ROUTES}, whose every
+ * entry is classified by a person's assurance, and no client method, because no
+ * person's software calls it. A deployment holding no acknowledgement key answers
+ * `503 acknowledgement_signing_not_configured`, never an empty set a verifier would
+ * read as "Cayso signs nothing".
+ */
+export declare const ACKNOWLEDGEMENT_KEYS_ROUTE: {
+    readonly method: "GET";
+    readonly path: "/api/acknowledgement-keys";
+};

package/dist/routes.js

@@ -99,6 +99,16 @@
  * 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`
@@ -124,13 +134,34 @@
  * authorisation under the owner's assertion (`present-standing-authorisation`,
  * CMTY-0018 §1). A person is behind it, so it is classified by a person's
  * assurance like every other entry. It names no wallet: the wallet is the verified
- * holder's own. It is published before it is served.
+ * holder's own. Published at `0.25.0` and served from `0.30.0` (CAY-0094).
+ *
+ * `revokeStandingAuthorisation` withdraws one (`revoke-standing-authorisation`). It
+ * is its own path for citizenship's reason, and a `POST` for cancelling's: nothing is
+ * deleted. The authorisation's row stays, and so does its Instance key's binding to
+ * the wallet; the revocation is a row of its own beside them. The body names the
+ * authorisation's `jti` and no wallet.
+ *
+ * `bindNode` binds a Node to the wallet its presenting Instance key is already bound
+ * to (`bind-node`, CAY-0095), under the owner's assertion. A person is behind it, so
+ * it is classified by a person's assurance. The body carries the Node ID signed by the
+ * Instance key and that key's public half, and no wallet: the wallet is the one the
+ * key is bound to, which must be the verified holder's own. A `POST` to a collection
+ * of bindings, because a Node is bound once and a repeat answers the same.
  *
  * The Contribution Store's settlement assertion is presented by no person. Its path
  * is {@link CLOUD_SETTLEMENT_ROUTE}, outside this table, because every entry here is
  * mapped in `OPERATION_FOR_ROUTE` to the assurance a person needs, and `null` there
  * means "carries no identity", which is false of an assertion a registered issuer
- * signed.
+ * signed. The Store's read of whether a Node is bound,
+ * {@link NODE_BINDING_QUERY_ROUTE}, is outside it for the same reason.
+ *
+ * ## Why Cayso's acknowledgement keys are outside this table too
+ *
+ * {@link ACKNOWLEDGEMENT_KEYS_ROUTE} publishes the public half of the key Cayso signs
+ * an authorisation acknowledgement with. It carries no identity at all, so it is not
+ * a person's operation either, and it is read by the Percayso Cloud's software rather
+ * than by a person's, so the client has no method for it.
  */
 export const ROUTES = {
     wallet: { method: 'GET', path: '/api/wallet' },
@@ -143,12 +174,19 @@ export const ROUTES = {
     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' },
     requestBuyBack: { method: 'POST', path: '/api/buy-backs' },
     marketplaceOrder: { method: 'POST', path: '/api/marketplace/orders' },
     standingAuthorisation: { method: 'POST', path: '/api/cloud/standing-authorisations' },
+    revokeStandingAuthorisation: {
+        method: 'POST',
+        path: '/api/cloud/standing-authorisation-revocations',
+    },
+    bindNode: { method: 'POST', path: '/api/cloud/node-bindings' },
     version: { method: 'GET', path: '/api/version' },
 };
 /**
@@ -163,9 +201,45 @@ export const ROUTES = {
  * in {@link ROUTES}, whose every entry is classified by a person's assurance. The
  * client has no method for it, because no person's software calls it.
  *
- * Published before it is served.
+ * Published at `0.25.0` and served from `0.30.0` (CAY-0096): a settled period is one
+ * `contribution_settlement` movement per paid contribution row and one
+ * `consumption_settlement` movement per consumption row, written whole or not at all.
  */
 export const CLOUD_SETTLEMENT_ROUTE = {
     method: 'POST',
     path: '/api/cloud/settlement-assertions',
 };
+/**
+ * Where the Percayso Cloud's Contribution Store asks whether one Node is bound to a
+ * wallet (CMTY-0018 §4, CAY-0095), so it can carry an unbound Node's rows withheld
+ * (`node_not_bound`) rather than pay them to nobody.
+ *
+ * **Authenticated by the registered Store issuer, exactly as
+ * {@link CLOUD_SETTLEMENT_ROUTE} is, and never by a person.** The body is the Store's
+ * own signed query, naming the one Node it asks about, so a captured query answers
+ * for that Node and no other. A person issuer's key is never the Store's, so a query
+ * a person signed is refused. It answers `{ nodeId, bound }` and nothing else: no
+ * wallet, holder, Citizen or date crosses to the Cloud. A `POST` because the question
+ * travels signed in the body; nothing is written. Not in {@link ROUTES}, and no
+ * client method, because no person's software calls it.
+ */
+export const NODE_BINDING_QUERY_ROUTE = {
+    method: 'POST',
+    path: '/api/cloud/node-binding-queries',
+};
+/**
+ * Where Cayso publishes the public half of every key it signs an authorisation
+ * acknowledgement with (CMTY-0018 §1, CMTY-0022 row 9): a JSON Web Key Set the
+ * Percayso Cloud reads to verify an acknowledgement an Instance hands it.
+ *
+ * **An unauthenticated read**, because a public key is public: it carries no
+ * identity, names no wallet and moves nothing. Not in {@link ROUTES}, whose every
+ * entry is classified by a person's assurance, and no client method, because no
+ * person's software calls it. A deployment holding no acknowledgement key answers
+ * `503 acknowledgement_signing_not_configured`, never an empty set a verifier would
+ * read as "Cayso signs nothing".
+ */
+export const ACKNOWLEDGEMENT_KEYS_ROUTE = {
+    method: 'GET',
+    path: '/api/acknowledgement-keys',
+};

package/dist/schema-types.d.ts

@@ -23,7 +23,8 @@
  * consumer's business, Piper's or the Percayso Cloud's, and a schema that
  * enumerated the operator surface would have published it (CAY-0026, Amendment 3;
  * CLAUDE.md). The Contribution Store's settlement path is published, but under
- * `issuerRoutes`, apart from the routes a person calls. The generator only ever sees this package, so the
+ * `issuerRoutes`, apart from the routes a person calls, and Cayso's acknowledgement keys
+ * under `keyRoutes`. The generator only ever sees this package, so the
  * internal surface is absent by construction.
  *
  * The one part of the operator surface that IS published — the three reads on the
@@ -129,10 +130,19 @@ export interface ContractSchema {
     /**
      * The routes authenticated by a registered issuer (CAY-0030) rather than by a
      * person, and therefore not in `ROUTES`: today the Contribution Store's
-     * settlement path (`CLOUD_SETTLEMENT_ROUTE`, CMTY-0018 §2). Kept apart from
+     * settlement path (`CLOUD_SETTLEMENT_ROUTE`, CMTY-0018 §2) and its read of whether a
+     * Node is bound (`NODE_BINDING_QUERY_ROUTE`, CAY-0095). Kept apart from
      * {@link routes} so that no consumer reads one as the other.
      */
     readonly issuerRoutes: Readonly<Record<string, SchemaRoute>>;
+    /**
+     * The unauthenticated reads that publish the public half of a key Cayso signs
+     * with, and therefore not in `ROUTES` either: today the authorisation
+     * acknowledgement keys (`ACKNOWLEDGEMENT_KEYS_ROUTE`, CAY-0093). No credential
+     * travels with them, so they are apart from both {@link routes} and
+     * {@link issuerRoutes}.
+     */
+    readonly keyRoutes: Readonly<Record<string, SchemaRoute>>;
     readonly types: Readonly<Record<string, SchemaType>>;
     /**
      * The operator reads an operator app's server calls, and their types — under

package/dist/schema.d.ts

@@ -10,15 +10,27 @@
  * none of this, and importing it does nothing but hand back a frozen data value
  * and its types (CLAUDE.md: packages have no side effects on import).
  *
- * ## This is a diagnostic, NOT a replacement for depending on the package
+ * ## A published, versioned surface — and the one a Go consumer depends on
  *
- * The schema exists so a running deployment can *report* the surface it was built
- * against — for the version endpoint, for the contract test, for an operator
- * eyeballing a mismatch. It is emphatically not a runtime type system: a consumer
- * gets its compile-time guarantees by depending on `@percayso-community/cayso-contracts` and its
- * types, which do not exist at runtime to be fetched. Fetching this schema to
- * drive validation instead of depending on the package would re-implement, badly,
- * the guarantee the package already gives for free (CAY-0026, and the README).
+ * Two consumers read this descriptor, in two ways, and both are depending on the
+ * package (CAY-0026 Amendment 3; CMTY-0018 §3 as amended):
+ *
+ *   - **A TypeScript consumer imports the types** and the compiler holds the
+ *     surface; for it this descriptor is a tool *about* the contract — the version
+ *     endpoint, the CI contract test, an operator eyeballing a mismatch — and never
+ *     a runtime type system standing in for the import.
+ *   - **A consumer in another language generates from this entry point of the
+ *     published tarball at a pinned version**, and fails its own build when its
+ *     generated types drift from the schema. The Percayso Cloud is that consumer: it
+ *     is written in Go, cannot import a TypeScript type, and generates its types for
+ *     the two seams in `cloud-settlement` from the tarball it pins. The pin is its
+ *     lockfile entry and the regeneration is its compile. The schema ships as a JS
+ *     module only, which is why the generator reads the tarball.
+ *
+ * What is refused is reading the schema OFF THE WIRE (`GET /api/version/schema`)
+ * as a substitute for pinning the package: that couples a consumer's build to a
+ * deployment's uptime and replaces a pinned version with whatever is deployed. The
+ * endpoint reports a running deployment; the package is the contract (the README).
  */
 export type { ContractSchema, ScalarKind, SchemaProperty, SchemaOperatorRoute, SchemaOperatorSurface, SchemaRoute, SchemaType, SchemaTypeNode, } from './schema-types.js';
 export { CONTRACT_SCHEMA } from './contract-schema.generated.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@percayso-community/cayso-contracts",
-  "version": "0.27.0",
+  "version": "0.30.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": {