@percayso-community/cayso-contracts 0.29.0 → 1.0.0

package/dist/client.d.ts

@@ -24,6 +24,23 @@
  * so each attempt gets a fresh one. That the retry re-fetches is a decision, not
  * an accident.
  *
+ * ## A second assertion, on the Organisation operations alone
+ *
+ * An act on an Organisation Wallet needs BizID's authority assertion beside Percayso
+ * ID's (CAY-0100 §4). The three methods that can be one take an optional
+ * {@link AuthorityAssertionProvider} as their last argument, and nothing else does.
+ * Its `getAuthorityAssertion()` is called under exactly the discipline above: inside
+ * each attempt, beside `getAssertion()`, never cached, and re-fetched on a retry,
+ * because the authority assertion is short-lived and single-use too. It travels in
+ * its own header, {@link AUTHORITY_ASSERTION_HEADER}, never in `Authorization`.
+ *
+ * It is per CALL rather than a client option, and that is the point. BizID mints an
+ * authority for one operation and one Organisation, and these methods name no
+ * Organisation, so only the caller knows which Organisation this act is for. A
+ * client-wide provider would have to guess, or would hand every Organisation
+ * operation the same authority. Passing none sends no header, and the request is
+ * exactly the request a `0.30.0` client sent.
+ *
  * ## One method per route, no method that is not
  *
  * Every method reads its method and path from `ROUTES` — no URL is hand-written
@@ -69,7 +86,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 { StandingAuthorisationAcknowledged, StandingAuthorisationRequest, StandingAuthorisationRevocationRequest, StandingAuthorisationRevoked, NodeBindingRequest, NodeBound } from './cloud-settlement.js';
 import type { CitizenTransferMade, CitizenTransferRequest } from './citizen-transfer.js';
 import type { CommercialPaymentMade, CommercialPaymentRequest } from './commercial-payment.js';
 import type { HandleChangeCharged, HandleChangeReceiptReadResponse } from './handle-change.js';
@@ -107,6 +124,19 @@ export interface CaysoClientOptions {
      */
     warn?: (message: string) => void;
 }
+/**
+ * Where an Organisation operation gets BizID's authority assertion for this one act
+ * (CAY-0100 §4): the second credential, beside the one `getAssertion` supplies.
+ *
+ * Called before EVERY attempt, never once and never cached, for the reason
+ * `getAssertion` is: the credential is short-lived and single-use, so one minted for
+ * a first attempt must not be presented again by a retry. The value is the compact
+ * JWS BizID minted, sent in {@link AUTHORITY_ASSERTION_HEADER} exactly as returned.
+ */
+export interface AuthorityAssertionProvider {
+    /** Called before every attempt. Authority assertions are short-lived, so never cache one. */
+    getAuthorityAssertion(): Promise<string>;
+}
 /**
  * One method per entry in `ROUTES`, and no method that is not. `getMyWallet`
  * answers `null` where the contract says a wallet may not exist yet, rather than
@@ -166,8 +196,12 @@ export interface CaysoClient {
      * carries no idempotency key and a repeat is the same act rather than a second
      * one. A credential carrying no organisation authority is refused; absence
      * provisions nothing.
+     *
+     * `authority` supplies BizID's authority assertion for `provision-organisation`
+     * (CAY-0100 §4). Optional, and sent only when given: no route reads it until the
+     * binding is served, and from then an Organisation operation without it is refused.
      */
-    provisionOrganisation(): Promise<OrganisationView>;
+    provisionOrganisation(authority?: AuthorityAssertionProvider): Promise<OrganisationView>;
     /**
      * Authorise a purchase — or REPLAY one (CAY-0032). Posting the same
      * `idempotencyKey` twice returns the ORIGINAL authorisation, at the original
@@ -184,8 +218,12 @@ export interface CaysoClient {
      * `'terminal'` means the key's purchase has finished and will not change: a
      * repeat of it will keep answering `'terminal'` forever, and the remedy is a new
      * purchase under a NEW key.
+     *
+     * `authority` supplies BizID's authority assertion for a purchase on behalf of an
+     * Organisation Wallet, when `onBehalfOfWalletId` names one (CAY-0100 §4a). A
+     * Citizen's own purchase needs none and passes none.
      */
-    authorisePurchase(req: PurchaseRequest): Promise<PurchaseAuthorised | PurchaseTerminal>;
+    authorisePurchase(req: PurchaseRequest, authority?: AuthorityAssertionProvider): Promise<PurchaseAuthorised | PurchaseTerminal>;
     getPurchase(purchaseId: string): Promise<PurchaseResult>;
     /**
      * Cancel a purchase the caller started, releasing its reservation (CAY-0032).
@@ -213,8 +251,11 @@ export interface CaysoClient {
      * thrown {@link CaysoApiError} whose `code` is a `CommercialPaymentRefusal`
      * member, one of the gate's codes, or a seam code, as {@link authorisePurchase}'s
      * refusals do. A refusal means nothing moved.
+     *
+     * `authority` supplies BizID's authority assertion on the `'mandate'` route
+     * (CAY-0100 §4a). The `'payment-allowance'` route needs none and passes none.
      */
-    makeCommercialPayment(req: CommercialPaymentRequest): Promise<CommercialPaymentMade>;
+    makeCommercialPayment(req: CommercialPaymentRequest, authority?: AuthorityAssertionProvider): 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).
@@ -304,10 +345,31 @@ export interface CaysoClient {
      * 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.
+     * of the gate's codes, or a seam code, and means nothing was bound. Each
+     * presentation answers a freshly signed acknowledgement.
      */
     presentStandingAuthorisation(req: StandingAuthorisationRequest): Promise<StandingAuthorisationAcknowledged>;
+    /**
+     * Revoke a standing authorisation the caller's wallet holds, named by its `jti`,
+     * under the owner's assertion (`revoke-standing-authorisation`, CAY-0094).
+     *
+     * Safe to repeat: revoking a revoked authorisation answers `revoked` again and
+     * writes nothing. A refusal arrives as a thrown {@link CaysoApiError} whose `code`
+     * is a `StandingAuthorisationRevocationRefusal` member, one of the gate's codes, or
+     * a seam code, and means nothing was written.
+     */
+    revokeStandingAuthorisation(req: StandingAuthorisationRevocationRequest): Promise<StandingAuthorisationRevoked>;
+    /**
+     * Bind a Node to the wallet the presenting Instance key is already bound to, under
+     * the owner's assertion (`bind-node`, CAY-0095). The key must have been bound to the
+     * caller's wallet by a standing authorisation it presented; this binds no key.
+     *
+     * Safe to repeat: binding a bound Node to the same wallet answers `bound` again and
+     * writes nothing. A refusal arrives as a thrown {@link CaysoApiError} whose `code` is
+     * a `NodeBindingRefusal` member, one of the gate's codes, or a seam code, and means
+     * nothing was bound.
+     */
+    bindNode(req: NodeBindingRequest): Promise<NodeBound>;
     getVersion(): Promise<CaysoVersion>;
 }
 /**

package/dist/client.js

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { CONTRACT_VERSION, NOT_PROVISIONED } from './index.js';
+import { AUTHORITY_ASSERTION_HEADER, CONTRACT_VERSION, NOT_PROVISIONED } from './index.js';
 import { ROUTES } from './routes.js';
 // --- The retry mechanism -----------------------------------------------------
 // These are this slice's own mechanism, not economics: an attempt count, a
@@ -110,6 +110,16 @@ function buildClient(options, internals) {
             if (spec.idempotencyKey !== undefined && spec.idempotencyKey.length > 0) {
                 headers['Idempotency-Key'] = spec.idempotencyKey;
             }
+            // The second credential, under the first one's discipline: per attempt, never
+            // cached, and in a header of its own (CAY-0100 §4). Absent unless the caller
+            // passed a provider, so every other request is unchanged. An empty value is sent
+            // as no header, as an empty key is above, so the server reads it as missing
+            // rather than as present and malformed.
+            if (spec.authority !== undefined) {
+                const authority = await spec.authority.getAuthorityAssertion();
+                if (authority.length > 0)
+                    headers[AUTHORITY_ASSERTION_HEADER] = authority;
+            }
             const init = { method: spec.method, headers };
             if (spec.body !== undefined)
                 init.body = JSON.stringify(spec.body);
@@ -190,7 +200,7 @@ function buildClient(options, internals) {
                 idempotent: true,
             });
         },
-        async provisionOrganisation() {
+        async provisionOrganisation(authority) {
             return requestJson({
                 method: ROUTES.organisationProvision.method,
                 path: ROUTES.organisationProvision.path,
@@ -198,9 +208,10 @@ function buildClient(options, internals) {
                 // is: the operation is idempotent on the attested Organisation ID, so a
                 // repeat is the same act rather than a second one.
                 idempotent: true,
+                authority,
             });
         },
-        async authorisePurchase(req) {
+        async authorisePurchase(req, authority) {
             return requestJson({
                 method: ROUTES.purchaseAuthorise.method,
                 path: ROUTES.purchaseAuthorise.path,
@@ -208,9 +219,10 @@ function buildClient(options, internals) {
                 idempotent: typeof req.idempotencyKey === 'string' && req.idempotencyKey.length > 0,
                 body: req,
                 idempotencyKey: req.idempotencyKey,
+                authority,
             });
         },
-        async makeCommercialPayment(req) {
+        async makeCommercialPayment(req, authority) {
             return requestJson({
                 method: ROUTES.commercialPayment.method,
                 path: ROUTES.commercialPayment.path,
@@ -219,6 +231,7 @@ function buildClient(options, internals) {
                 idempotent: typeof req.idempotencyKey === 'string' && req.idempotencyKey.length > 0,
                 body: req,
                 idempotencyKey: req.idempotencyKey,
+                authority,
             });
         },
         async makeCitizenTransfer(req) {
@@ -309,6 +322,24 @@ function buildClient(options, internals) {
                 body: req,
             });
         },
+        async revokeStandingAuthorisation(req) {
+            return requestJson({
+                method: ROUTES.revokeStandingAuthorisation.method,
+                path: ROUTES.revokeStandingAuthorisation.path,
+                // Safe to repeat: a revoked authorisation revoked again answers the same.
+                idempotent: true,
+                body: req,
+            });
+        },
+        async bindNode(req) {
+            return requestJson({
+                method: ROUTES.bindNode.method,
+                path: ROUTES.bindNode.path,
+                // Safe to repeat: the same Node bound to the same wallet answers the same.
+                idempotent: true,
+                body: req,
+            });
+        },
         async getPurchase(purchaseId) {
             return requestJson({
                 method: ROUTES.purchaseResult.method,

package/dist/cloud-settlement.d.ts

@@ -4,11 +4,16 @@
  * assertion** the Contribution Store signs once per period and Cayso fails closed
  * on (CMTY-0018, as Cayso amended it on 5 October 2026).
  *
- * **This is the contract surface only.** Nothing here is served, settled or
- * stored: no route answers either seam yet, no movement kind exists for either
- * leg, and nothing binds a Node or an Instance key to a wallet. Those are later
- * slices. What is published is what the Cloud generates its own types from
- * (CMTY-0018 §3), so that neither side redeclares the other's half.
+ * **Both seams are served.** `present-standing-authorisation` binds an Instance key
+ * to the presenting holder's wallet and answers a signed acknowledgement, and
+ * `revoke-standing-authorisation` withdraws one (CAY-0094). `bind-node` binds a
+ * Node to the wallet its Instance key is already bound to, and the Store asks
+ * whether a Node is bound at {@link NODE_BINDING_QUERY_ROUTE} (CAY-0095). The Store
+ * presents each period's settlement assertion at {@link CLOUD_SETTLEMENT_ROUTE},
+ * and Cayso settles it whole, as one `contribution_settlement` movement per paid
+ * contribution row and one `consumption_settlement` movement per consumption row,
+ * or refuses it whole (CAY-0096). What is published is what the Cloud generates its
+ * own types from (CMTY-0018 §3), so that neither side redeclares the other's half.
  *
  * ## Two seams, two authorities
  *
@@ -21,6 +26,10 @@
  * Cayso issuer key, which the Instance hands to the Cloud. An Instance mediates and
  * does not vouch (CAY-0057): the acknowledgement is how Cayso vouches for an
  * Instance key the Cloud has never seen, without the Cloud learning whose it is.
+ * The owner withdraws it from the Instance the same way, under their money-grade
+ * assertion (`revoke-standing-authorisation`,
+ * `ROUTES.revokeStandingAuthorisation`); the Cloud learns of it when the last
+ * acknowledgement it holds expires, at the end of the next period.
  *
  * **The settlement assertion** is the Contribution Store's statement of one
  * period: contribution by Node, consumption by authorisation. It is presented by
@@ -54,6 +63,24 @@
  * package, not the record, is the shape the Cloud generates from (CAY-0026,
  * Amendment 3).
  *
+ * ## A Node is bound to the wallet its Instance key is bound to (CMTY-0018 §4)
+ *
+ * A Contributor's Node earns for its owner. The owner's Instance presents the Node
+ * under the owner's money-grade assertion (`bind-node`, `ROUTES.bindNode`), signed by
+ * the Instance key, and Cayso binds the Node to the wallet that key is already bound
+ * to — which must be the verified holder's own. Binding a Node binds no Instance key:
+ * a key is bound only by the first standing authorisation it presents (CAY-0094). A
+ * Node is bound once and never re-pointed, and there is no unbinding.
+ *
+ * A Core Node's owner is the Operator, so it is never bound to a Citizen Wallet
+ * (`core_node_not_bound`). Nothing in a Node ID says it is a Core Node; a deployment
+ * is told its Core Node IDs by configuration.
+ *
+ * The Store learns only whether a Node is bound ({@link NodeBindingStatus}), at
+ * {@link NODE_BINDING_QUERY_ROUTE}, authenticated by the registered Store issuer
+ * exactly as the settlement assertion is, and never by a person. The answer cannot
+ * name a wallet.
+ *
  * ## Fail closed on the whole assertion
  *
  * A settlement assertion is settled whole or not at all (CAY-0021, CMTY-0018 §2).
@@ -68,6 +95,15 @@
  * period's id and the idempotency key, and a replay answers what the first
  * presentation answered.
  *
+ * A **withheld** contribution row is carried and settles nothing: it writes no
+ * movement and does not refuse the period. How a later period pays what was withheld
+ * is open (CAY-0096 §5). A row of nought cents writes no movement either, though every
+ * check on it still runs. A **Core Node**'s qualified row of any amount but nought is
+ * refused with its own member, `contribution_node_is_a_core_node`: a Core Node's owner is
+ * the Operator, and where its contribution settles, if anywhere, is not designed
+ * (CAY-0096 §4). A Core Node row of nought cents is skipped and settles nothing, an
+ * interim rule pending that design (30 October 2026, cloud.platform#357).
+ *
  * ## What is not here
  *
  *   - **No Instance ID**, in any claim, row, request, answer or refusal (CAY-0059 §6).
@@ -79,14 +115,22 @@
  *   - **No figure.** The cap's ceiling, the authorisation's longest life, the
  *     period's length and rule, and every rate are canon figures read from one
  *     place. `period` is an opaque identifier; this package sets no value for it.
- *   - **No unconfigured adapter in either union.** A seam this deployment has not
+ *   - **No unconfigured adapter in any union.** A seam this deployment has not
  *     been told about — no Store issuer registered, no Cayso acknowledgement key, no
- *     ceiling configured — is a `503` in the refusal envelope's own code, spelled by
- *     the slice that serves the route, never a member here.
- *   - **No movement kind.** CMTY-0018 §2 proposes one per leg (CAY-0082's
- *     pattern). The reasons a movement can be refused for — a short wallet, a
- *     contended carve — arrive with the slice that designs those kinds, as a new
- *     contract version.
+ *     ceiling configured — is a `503` with a `CaysoApiErrorCode` of its own, never a
+ *     member here: `acknowledgement_signing_not_configured`,
+ *     `standing_authorisation_cap_ceiling_not_configured`,
+ *     `standing_authorisation_life_ceiling_not_configured` and
+ *     `standing_authorisation_store_not_configured` for the standing authorisation;
+ *     `node_binding_store_not_configured` and `core_node_ids_not_configured` for
+ *     binding a Node; `node_binding_store_not_configured`,
+ *     `core_node_ids_not_configured` and `contribution_store_issuer_not_configured`
+ *     for the Store's read; and, for the settlement assertion,
+ *     `cloud_settlement_store_not_configured` — no Treasury, so nowhere to settle —
+ *     `core_node_ids_not_configured` and `contribution_store_issuer_not_configured`.
+ *   - **No movement kind in this package's unions.** The two kinds a settlement
+ *     writes are `MovementKind` members like every other (CAY-0096); what crosses
+ *     here is only whether the period settled, and why it did not.
  *   - **No chain height.** A period is bounded in UTC seconds until there is a chain
  *     to read (CAY-0016); the height a Store read is a later version's member.
  */
@@ -189,6 +233,38 @@ export interface AuthorisationAcknowledgementClaims {
     /** Expiry, in **seconds** since the Unix epoch. */
     readonly exp: number;
 }
+/**
+ * The id of one Cayso acknowledgement key: the RFC 7638 SHA-256 thumbprint of its
+ * public half, unpadded base64url, and the `kid` in an acknowledgement's header.
+ * Derived rather than minted, so a key id cannot be re-pointed at a different key.
+ * Opaque to a consumer: compare it, never parse it.
+ */
+export type AcknowledgementKeyId = string;
+/**
+ * The public half of one key Cayso signs an {@link AuthorisationAcknowledgementClaims}
+ * with: an Ed25519 public JSON Web Key (RFC 8037), and nothing private. Its `kid` is
+ * the thumbprint of `crv`, `kty` and `x`, so a verifier can check that the key it
+ * selected is the key the header named.
+ */
+export interface AcknowledgementPublicKey {
+    readonly kty: 'OKP';
+    readonly crv: 'Ed25519';
+    /** The public key, unpadded base64url. */
+    readonly x: string;
+    readonly kid: AcknowledgementKeyId;
+    readonly alg: 'EdDSA';
+    readonly use: 'sig';
+}
+/**
+ * Every key a Cayso acknowledgement may be verified under, as a JSON Web Key Set
+ * (CAY-0093). A key is listed before it signs and stays listed after it stops
+ * signing, so a verifier selects by `kid` and never by position. Answered at
+ * `ACKNOWLEDGEMENT_KEYS_ROUTE`; a deployment holding no key answers
+ * `503 acknowledgement_signing_not_configured`, never an empty set.
+ */
+export interface AcknowledgementKeySet {
+    readonly keys: readonly AcknowledgementPublicKey[];
+}
 /** Cayso holds the authorisation, and here is its acknowledgement for the Cloud. */
 export interface StandingAuthorisationAcknowledged {
     readonly outcome: 'acknowledged';
@@ -255,6 +331,208 @@ export type StandingAuthorisationRefusal =
  | 'cap_not_delegable'
 /** The Instance key is already bound to a different wallet, and a key spends from one. */
  | 'instance_key_bound_to_another_wallet';
+/**
+ * The owner withdrawing a standing authorisation from their Instance, under the
+ * owner's assertion (`revoke-standing-authorisation`, CAY-0094). It names the
+ * authorisation by its `jti` and nothing else: whose wallet it is comes from the
+ * assertion, never from the request.
+ */
+export interface StandingAuthorisationRevocationRequest {
+    /** The revoked authorisation's `jti`. */
+    readonly authorisation: string;
+}
+/**
+ * The authorisation is revoked: presented again, it is refused
+ * `authorisation_revoked`. Its Instance key stays bound to the wallet, so the key
+ * cannot be re-pointed at another. Revoking it again answers this again.
+ */
+export interface StandingAuthorisationRevoked {
+    readonly outcome: 'revoked';
+    /** The `jti` the request named, echoed so a caller can match the answer to its act. */
+    readonly authorisation: string;
+}
+/** The revocation was refused, with one member of the closed union. Nothing was written. */
+export interface StandingAuthorisationRevocationRefused {
+    readonly outcome: 'refused';
+    readonly error: StandingAuthorisationRevocationRefusal;
+}
+/** The ONE declared answer to `revoke-standing-authorisation`, discriminated by `outcome`. */
+export type StandingAuthorisationRevocationResponse = StandingAuthorisationRevoked | StandingAuthorisationRevocationRefused;
+/**
+ * Why a revocation was refused. Closed, like {@link StandingAuthorisationRefusal}:
+ * a new reason is a new member and a contract version.
+ */
+export type StandingAuthorisationRevocationRefusal = 
+/**
+ * The verification method is outside the money-grade assurance profile
+ * (`ASSURANCE_POLICY['revoke-standing-authorisation']`). `dev-bypass` is never
+ * inside it.
+ */
+'assurance_not_money_grade'
+/** No wallet is bound to the verified holder now, so there is nothing they hold to revoke. */
+ | 'wallet_has_no_live_binding'
+/**
+ * No authorisation with this `jti` is held for the caller's wallet: it was never
+ * presented, or it was presented for another wallet. One member for both, so the
+ * route is no oracle for which `jti`s exist.
+ */
+ | 'authorisation_not_held_by_this_wallet';
+/**
+ * The Instance key's statement naming one Node (CMTY-0018 §4, CAY-0095): signed by
+ * the Instance key in CAY-0072's format, whose header `kid` is `iss`. It says only
+ * "this key presents this Node". Which wallet the Node is bound to is not a claim:
+ * it is the wallet that Instance key is already bound to, on Cayso's side, which is
+ * the verified holder's own.
+ */
+export interface NodePresentationClaims {
+    /** The Instance key that signed it. The same value as the header's `kid`. */
+    readonly iss: InstanceKeyId;
+    /** Exactly `'cayso'`, and checked, not merely present. */
+    readonly aud: 'cayso';
+    /** The Node being bound, as the Cloud's Node Registry holds it. */
+    readonly node_id: NodeId;
+    /** Issued-at, in **seconds** since the Unix epoch. */
+    readonly iat: number;
+    /** Expiry, in **seconds** since the Unix epoch. */
+    readonly exp: number;
+}
+/**
+ * The Instance binding a Node to its owner's wallet, under the owner's assertion
+ * (`bind-node`, CAY-0095). The Instance key must already be bound to the verified
+ * holder's wallet, by a standing authorisation it presented (CAY-0094): binding a
+ * Node binds no key.
+ */
+export interface NodeBindingRequest {
+    /** The compact {@link NodePresentationClaims}, exactly as the Instance key signed it. */
+    readonly nodePresentation: string;
+    /**
+     * The Instance key's public half, as the JSON text of a public JSON Web Key. Its
+     * RFC 7638 thumbprint must be the presentation's `kid`, so the key that verifies
+     * the presentation is the key it names, and no other.
+     */
+    readonly instanceKey: string;
+}
+/**
+ * The Node is bound to the verified holder's wallet. Answered for the presentation
+ * that bound it and for every repeat of the same binding, in the same shape: a
+ * repeat writes nothing. It names the Node and no wallet.
+ */
+export interface NodeBound {
+    readonly outcome: 'bound';
+    /** The Node the presentation named, echoed so a caller can match the answer to its act. */
+    readonly nodeId: NodeId;
+}
+/** The binding was refused, with one member of the closed union. Nothing was bound. */
+export interface NodeBindingRefused {
+    readonly outcome: 'refused';
+    readonly error: NodeBindingRefusal;
+}
+/** The ONE declared answer to `bind-node`, discriminated by `outcome`. */
+export type NodeBindingResponse = NodeBound | NodeBindingRefused;
+/**
+ * Why a Node binding was refused. Closed, like {@link StandingAuthorisationRefusal}:
+ * a new reason is a new member and a contract version. Every member means the same
+ * thing: nothing was bound. There is no unbinding, so no member is about one.
+ */
+export type NodeBindingRefusal = 
+/**
+ * The verification method is outside the money-grade assurance profile
+ * (`ASSURANCE_POLICY['bind-node']`). `dev-bypass` is never inside it.
+ */
+'assurance_not_money_grade'
+/**
+ * Not a compact assertion in CAY-0072's format, or its claims are not exactly the
+ * closed set of {@link NodePresentationClaims} with `aud` `'cayso'`.
+ */
+ | 'node_presentation_malformed'
+/** The Instance key presented is not a public JSON Web Key Cayso can verify with. */
+ | 'instance_key_malformed'
+/**
+ * The presented key's thumbprint is not the presentation's `kid`, `iss` is not that
+ * `kid`, or the signature does not verify over the bytes presented. One member for
+ * all three: in each, the key presented did not sign this presentation.
+ */
+ | 'node_presentation_not_signed_by_its_instance_key'
+/** `exp` is at or before now, or `iat` is further ahead of now than the clock-skew tolerance. */
+ | 'node_presentation_not_current'
+/**
+ * The Instance key is not bound to the verified holder's wallet: it was never
+ * bound, it is bound to another wallet, or the holder has no wallet now. One member
+ * for all three, so the route is no oracle for whose a key is.
+ */
+ | 'instance_key_not_bound_to_holder'
+/**
+ * The Node is a Core Node, which this deployment is told of by configuration. A
+ * Core Node's owner is the Operator (CMTY-0018 §4), so it is bound to no Citizen
+ * Wallet.
+ */
+ | 'core_node_not_bound'
+/** The Node is already bound to a different wallet. A binding is never re-pointed. */
+ | 'node_bound_to_another_wallet';
+/**
+ * The Contribution Store's question about one Node (CAY-0095): signed by a key of
+ * the registered Store issuer, in CAY-0072's format, whose header `kid` names that
+ * key. It asks whether the Node is bound, and nothing about to whom.
+ */
+export interface NodeBindingQueryClaims {
+    readonly iss: ContributionStoreIssuer;
+    /** Exactly `'cayso'`. */
+    readonly aud: 'cayso';
+    /** The Node asked about. */
+    readonly node_id: NodeId;
+    /** Issued-at, in **seconds** since the Unix epoch. */
+    readonly iat: number;
+    /** Expiry, in **seconds** since the Unix epoch. */
+    readonly exp: number;
+}
+/**
+ * The Contribution Store asking whether a Node is bound, under its own registered
+ * issuer and no person's assertion, at `NODE_BINDING_QUERY_ROUTE`.
+ */
+export interface NodeBindingQueryRequest {
+    /** The compact {@link NodeBindingQueryClaims}, exactly as the Store signed it. */
+    readonly nodeBindingQuery: string;
+}
+/**
+ * Cayso's answer: whether the Node is bound to a wallet, and **nothing else**. No
+ * wallet, no holder, no Citizen, no date, no Instance ID (CAY-0006, CAY-0059 §6). A
+ * Store that learns a Node is bound pays its rows; which wallet is paid is Cayso's
+ * to resolve at settlement, on its own side. A Node this deployment is told is a Core
+ * Node is answered `bound: false`, even if a Citizen bound it before it was named
+ * Core. Exactly two members, and the contract tests pin that no third can be added
+ * unnoticed.
+ */
+export interface NodeBindingStatus {
+    readonly nodeId: NodeId;
+    readonly bound: boolean;
+}
+/** The query was refused, with one member of the closed union. Nothing was read. */
+export interface NodeBindingQueryRefused {
+    readonly outcome: 'refused';
+    readonly error: NodeBindingQueryRefusal;
+}
+/**
+ * Why the Store's query was refused. Closed. A query signed by anybody but the
+ * registered Store issuer, a person issuer included, is `node_binding_query_issuer_not_recognised`.
+ */
+export type NodeBindingQueryRefusal = 
+/**
+ * Not a compact assertion in CAY-0072's format, or its claims are not exactly the
+ * closed set of {@link NodeBindingQueryClaims} with `aud` `'cayso'`.
+ */
+'node_binding_query_malformed'
+/**
+ * `iss` is not the Store issuer this deployment's registry holds, the issuer or the
+ * `kid` is revoked, or the `kid` is not one of its keys. A person issuer is never
+ * the Store issuer.
+ */
+ | 'node_binding_query_issuer_not_recognised'
+/** `iss` names the Contribution Store of another environment. */
+ | 'node_binding_query_issuer_for_another_environment'
+/** The signature does not verify over the bytes presented. */
+ | 'node_binding_query_signature_invalid'
+/** `exp` is at or before now, or `iat` is further ahead of now than the clock-skew tolerance. */
+ | 'node_binding_query_not_current';
 /** The kind of contribution a row measures: the three of the Community map's #3. Closed. */
 export type ContributionType = 'storage' | 'compute' | 'full-node';
 /**
@@ -429,30 +707,71 @@ export type SettlementAssertionLevelRefusal =
  | 'settlement_issued_in_the_future'
 /** `jti` is not the period's id. */
  | 'settlement_jti_not_the_period'
+/**
+ * The period is not one this deployment's period rules made: its id is not the id a
+ * recognised rule gives the period containing `starts_at`, or its instants are not
+ * that period's. A deployment that recognises no rule refuses every period.
+ */
+ | 'settlement_period_not_recognised'
+/** The period's `ends_at` is still ahead of now, beyond the clock-skew tolerance. */
+ | 'settlement_period_not_ended'
 /**
  * A different assertion already settled this period. The two cannot both be the
  * period, so the second is refused, and the first stands.
  */
  | 'settlement_period_already_settled_differently'
 /** A leg's rows do not add to its total. Refused before any row is read. */
- | 'settlement_totals_do_not_add';
+ | 'settlement_totals_do_not_add'
+/**
+ * Another movement kept changing a wallet the settlement draws from, and the carve
+ * gave up. Nothing was written; presenting the same assertion again is safe.
+ */
+ | 'settlement_carve_contended';
 /** Why the first failing contribution row failed. */
 export type ContributionRowRefusal = 
 /**
- * A qualified row names a Node bound to no wallet. An unbound Node's row is
- * carried withheld (`node_not_bound`) and never settled to anybody.
+ * A qualified row names a Node bound to no wallet, or to a wallet that no longer
+ * has a holder. An unbound Node's row is carried withheld (`node_not_bound`) and
+ * never settled to anybody.
+ */
+'contribution_node_not_bound'
+/**
+ * A qualified row of more than nought cents names a Node this deployment is told is a
+ * Core Node. A Core Node's owner is the Operator (CMTY-0018 §4), so it settles to no
+ * Citizen Wallet. A nought row for a Core Node is skipped instead (interim, #357).
  */
-'contribution_node_not_bound';
+ | 'contribution_node_is_a_core_node'
+/** The Treasury holds too few unrestricted cents to pay this row. */
+ | 'contribution_treasury_short';
 /** Why the first failing consumption row failed. */
 export type ConsumptionRowRefusal = 
 /** The row cites an authorisation Cayso never acknowledged. */
 'consumption_authorisation_unknown'
-/** The row cites an authorisation its owner revoked before the period. */
+/**
+ * The row cites an authorisation its owner revoked before the period: no
+ * acknowledgement Cayso signed before the revocation covers any of it.
+ */
  | 'consumption_authorisation_revoked'
-/** The row's cap is not the cap the acknowledgement stated. */
+/**
+ * The row cites an authorisation that was not in force in the period: issued after
+ * the period ended, or expired at or before it began.
+ */
+ | 'consumption_authorisation_not_in_force'
+/**
+ * The row's cap is not the cap the acknowledgement stated, or the authorisation's
+ * period rule is not the rule that made this period.
+ */
  | 'consumption_cap_not_the_acknowledged_cap'
-/** The authorisation's running total in this period passes its cap at this row. */
- | 'consumption_over_cap';
+/**
+ * The authorisation's running total in this period passes its cap at this row. The
+ * Store clamps at the cap, so this is a Store defect, and it is never softened.
+ */
+ | 'consumption_over_cap'
+/**
+ * The paying wallet holds too few unrestricted cents for this row. Restricted cents
+ * never pay a consumption settlement (CAY-0096 §2).
+ */
+ | 'consumption_wallet_short';
 /**
  * Every reason a settlement assertion can be refused: the assertion's own, and each
  * leg's. Closed, so a consumer's map over it is total.