@percayso-community/cayso-contracts 0.24.0 → 0.27.0

package/README.md

@@ -12,26 +12,45 @@ literal `0` to `number` — so the one structural guarantee in that surface dies
 the HTTP boundary. The fix is a single published package whose types a consumer
 imports rather than retypes.
 
-## The Piper-facing surface only
-
-Published here: the record and response types, the closed failure-reason union,
-the assertion claims and the route constants — the surface Piper reads.
-
-**Deliberately not published:** peer types, admin types, holdings and carves.
-They are not a consumer's business, and putting them on the public surface widens
-it for nothing.
+## The surface of every consumer outside this tree
+
+Published here: the record and response types, the closed failure-reason unions,
+the assertion claims and the route constants — the surface every consumer outside
+this repository reads (CAY-0026, Amendment 3). Piper is the first consumer. The
+Percayso Cloud is the second: its Contribution Store presents the settlement
+assertion to Cayso directly, and the Cloud generates its types from the `schema`
+entry point rather than typing Cayso's half by hand. The Cloud's two seams live in
+`cloud-settlement`, and the settlement path, which a registered issuer calls and
+no person does, is `CLOUD_SETTLEMENT_ROUTE`, published apart from `ROUTES`.
+
+**The operator read surface, on its own entry point** (CAY-0026, Amendment 4). Three
+reads an operator app's *server* calls — the movement list, the purchase list and the
+quickening ladder — are published at `@percayso-community/cayso-contracts/operator`:
+their paths and scopes, query inputs (wallet id, a half-open `[from, to)` window, a
+keyset cursor), rows and pages, and their closed refusal and not-configured bodies.
+Money is `Cents`, a wallet is named by its wallet id, and no Percayso identity
+appears on any row. It is not re-exported from the barrel, so Piper and the Cloud
+never import an operator vocabulary by accident, and the schema describes it under
+its own `operator` key rather than among the person-facing types. Cayso sends no
+CORS headers: these reads are for a server, never a browser. Widening the entry
+point beyond these three needs a further amendment.
+
+**Deliberately not published:** peer types, holdings and carves, and every operator
+route but those three reads. They are not a consumer's business, and putting them on
+the public surface widens it for nothing.
 
 **This package carries no numbers.** Amounts, rates, tiers, schedules and
 thresholds live in the canon PRD and are read from one place. None of them are
 restated here.
 
-## Three entry points
+## Four entry points
 
 | Import | What it gives you |
 |---|---|
 | `@percayso-community/cayso-contracts` | Types and constants. No runtime. |
 | `@percayso-community/cayso-contracts/client` | The thin client — fetch, assertion header, idempotent retry. |
 | `@percayso-community/cayso-contracts/schema` | A machine-readable descriptor of the published surface. |
+| `@percayso-community/cayso-contracts/operator` | The three operator reads' types and route constants, for an operator app's server. |
 
 The split is the point: a consumer wanting only the types takes on no runtime at
 all. The client owns the fetch, the assertion header and the idempotent retry.
@@ -63,9 +82,14 @@ describes. The thin client's `getVersion()` reads it and warns once, per client
 instance, when the server's contract *major* differs from the one the client was
 built against.
 
+After a minor bump that is additive on the wire, a deployment keeps the previous
+minor in `supportedContractVersions` for one release, so a consumer still pinned
+to it keeps working while it moves. A breaking bump drops it, and says so in the
+bump's changelog.
+
 Alongside it, `GET /api/version/schema` serves the same machine-readable
-descriptor as `@percayso-community/cayso-contracts/schema` — the Piper-facing surface only, with no
-operator, webhook or peer route. It exists for tooling and diagnostics.
+descriptor as `@percayso-community/cayso-contracts/schema` — the surface outside consumers read, with
+no operator, webhook or peer route. It exists for tooling and diagnostics.
 
 **It is not a substitute for depending on this package.** The descriptor is
 data; the guarantee is the *types*, and the types do not exist at runtime — they

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
@@ -353,15 +360,27 @@
  * checked. Neither is a second use of `'authorise-purchase'`, which brings sterling
  * in, or of `'make-commercial-payment'`, which is organisation-to-Citizen only.
  * Both are classified before they are served, and no route serves either yet.
+ *
+ * `'present-standing-authorisation'` is an owner delegating spending to their
+ * Instance on Percayso Cloud services (CMTY-0018 §1): the Instance presents the
+ * owner's standing authorisation, signed by the Instance key, under the owner's
+ * assertion, and Cayso answers with an acknowledgement the Cloud meters against.
+ * It is not a second use of `'make-commercial-payment'`: nothing moves when it is
+ * presented, and what it authorises is spending in later periods, settled by the
+ * 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';
+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
  * is published and carries the Piper-facing surface only (CAY-0026), and naming
  * an internal vocabulary here would publish a set of keys no consumer of this
  * contract may ever present. Where the closed set is kept instead is stated on
- * {@link ScopeKey}.
+ * {@link ScopeKey}. The three operator READ scopes are published, but on the
+ * `./operator` entry point (`OperatorReadScope`, CAY-0026 Amendment 4), for an
+ * operator app's server and not for this contract's consumers — so this type
+ * stays open, and the rest of the operator vocabulary stays unpublished.
  */
 export type InternalOperation = string;
 /**

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
@@ -452,6 +470,27 @@ export const ASSURANCE_POLICY = {
             "Platform's signed refund decision; the assertion shows the buyer is present, and it is held " +
             'to the same bar as the sale it refunds.',
     },
+    // An owner delegating spending to their Instance (CMTY-0018 §1). Money-grade, in
+    // the pattern of the commercial payment: what is authorised is cents leaving the
+    // holder's wallet in every later period, up to a cap, without the holder present.
+    // The passkey ceremony is the assertion's verification method, and the bar is
+    // the purchase path's, so a bar no issuer can yet clear does not shut the Cloud
+    // on every deployment. What limits the spending is the cap and its canon ceiling,
+    // and neither is an assurance question.
+    'present-standing-authorisation': {
+        operation: 'present-standing-authorisation',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: "Presenting a standing authorisation delegates spending from the holder's wallet to their " +
+            'Instance, up to a cap in every period, so it is money-grade: anything but the development ' +
+            'bypass. Nothing moves when it is presented; what it authorises moves later, without the ' +
+            'holder present, which is why the bar is applied here.',
+    },
 };
 /**
  * Every operation, as a value. Derived from {@link ASSURANCE_POLICY} for the same
@@ -484,11 +523,13 @@ 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',
     requestBuyBack: 'request-buy-back',
     marketplaceOrder: 'settle-marketplace-order',
+    standingAuthorisation: 'present-standing-authorisation',
     version: null,
 };
 /**

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

@@ -69,6 +69,8 @@
  */
 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';
@@ -212,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
@@ -264,6 +277,18 @@ export interface CaysoClient {
      * means nothing moved.
      */
     settleMarketplaceOrder(req: MarketplaceOrderRequest): Promise<MarketplaceOrderSettled>;
+    /**
+     * Present the owner's standing authorisation, signed by the Instance key, under the
+     * owner's assertion (`present-standing-authorisation`, CMTY-0018 §1), and receive
+     * Cayso's signed acknowledgement for the Percayso Cloud.
+     *
+     * Safe to repeat: the authorisation's `jti` is its own key, and presenting the same
+     * authorisation again binds nothing twice. A refusal arrives as a thrown
+     * {@link CaysoApiError} whose `code` is a `StandingAuthorisationRefusal` member, one
+     * of the gate's codes, or a seam code, and means nothing was bound. Published before
+     * the route is served.
+     */
+    presentStandingAuthorisation(req: StandingAuthorisationRequest): Promise<StandingAuthorisationAcknowledged>;
     getVersion(): Promise<CaysoVersion>;
 }
 /**

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,
@@ -270,6 +280,16 @@ function buildClient(options, internals) {
                 body: req,
             });
         },
+        async presentStandingAuthorisation(req) {
+            return requestJson({
+                method: ROUTES.standingAuthorisation.method,
+                path: ROUTES.standingAuthorisation.path,
+                // Safe to repeat: the authorisation's `jti` is its key, and the same
+                // authorisation presented again binds nothing twice.
+                idempotent: true,
+                body: req,
+            });
+        },
         async getPurchase(purchaseId) {
             return requestJson({
                 method: ROUTES.purchaseResult.method,