@percayso-community/cayso-contracts 0.29.0 → 0.30.0

package/README.md

@@ -21,7 +21,10 @@ 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`.
+no person does, is `CLOUD_SETTLEMENT_ROUTE`, published apart from `ROUTES`. The
+Cloud verifies Cayso's authorisation acknowledgement under a key it reads from
+`ACKNOWLEDGEMENT_KEYS_ROUTE`, an unauthenticated read of public keys, published
+apart from both.
 
 **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
@@ -49,16 +52,34 @@ restated here.
 |---|---|
 | `@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/schema` | A machine-readable descriptor of the published surface: the published, versioned surface a consumer in another language generates its types from. |
 | `@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.
 
 The `schema` entry point serves a data description of the same surface —
-generated from these very types, never hand-written — for tooling that needs the
-shape at runtime (a diff, a doc generator, a compatibility check). It is a
-diagnostic, **not** a stand-in for depending on the package: see below.
+generated from these very types, never hand-written. It is a published, versioned
+surface in its own right, and there are two ways to depend on this package through
+it, by language:
+
+1. **A TypeScript consumer imports the types**, and the compiler holds the surface.
+   Piper does this. For such a consumer the schema is a tool *about* the contract —
+   a diff, a doc generator, a compatibility check — and never a replacement for the
+   import.
+2. **A consumer in another language generates from the `schema` entry point of the
+   published tarball at a pinned version**, and treats a drift between its generated
+   types and the schema as a build failure. That *is* depending on the package: the
+   pin is the lockfile entry and the regeneration is the compile. The Percayso Cloud
+   is this consumer (`CAY-0026` Amendment 3; `CMTY-0018` §3 as amended): it is written
+   in Go, it cannot import a TypeScript type, and its generator reads the npm tarball
+   at a pinned version so that its Go types for the two Cloud seams in
+   `cloud-settlement` are never typed by hand. The package ships the schema as a JS
+   module only, which is why the generator reads the tarball and not a registry
+   endpoint.
+
+What stays refused is reading the schema off the wire as a substitute for either:
+see the version endpoint, below.
 
 ## Independent versioning
 
@@ -91,15 +112,18 @@ Alongside it, `GET /api/version/schema` serves the same machine-readable
 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
-are erased when TypeScript compiles. A consumer that reads the schema off the
-wire and validates against it has re-created Piper's original mistake by another
-route: hand-rolling the shape instead of importing it, and losing every
-compile-time guarantee the moment the wire description and the code drift. Import
-`@percayso-community/cayso-contracts` and let the compiler hold the surface. Read the schema
-endpoint when you are building a tool *about* the contract, never to stand in for
-having it.
+**The wire is not a substitute for depending on this package.** The descriptor
+served here is data about *this deployment*; the guarantee is the published
+package at a pinned version. A consumer that reads the schema off the wire and
+validates or generates against it has re-created Piper's original mistake by
+another route: it couples its build to a deployment's uptime, replaces a pinned
+version with whatever happens to be deployed at that moment, and loses every
+guarantee the moment the wire description and its code drift. Import
+`@percayso-community/cayso-contracts` and let the compiler hold the surface, or —
+in another language — generate from the `schema` entry point of the published
+tarball at a pinned version, as the Cloud does. Read the schema *endpoint* when
+you are building a tool *about* a running deployment, never to stand in for
+having the package.
 
 ## No dependencies
 

package/dist/assertion.d.ts

@@ -383,9 +383,19 @@
  * 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.
+ * no operation here.
+ *
+ * `'revoke-standing-authorisation'` is the owner withdrawing that delegation from
+ * their Instance (CAY-0094). It is its own operation rather than a mode of
+ * presenting, because one path carries one scope at CAY-0030's gate: a credential
+ * minted to revoke must not thereby delegate, nor the reverse.
+ *
+ * `'bind-node'` is the owner's Instance binding a Node to the wallet its Instance key
+ * is already bound to (CMTY-0018 §4, CAY-0095). Its own operation, because it decides
+ * where a Node's earnings land and binds no key: a credential minted to delegate
+ * spending must not thereby direct earnings, nor the reverse.
  */
-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' | 'change-handle' | 'read-handle-change-receipt' | 'place-quote' | 'withdraw-quote' | 'request-buy-back' | 'read-citizen-market' | 'read-marketplace-receipt' | 'settle-marketplace-order' | 'settle-marketplace-refund' | 'present-standing-authorisation';
+export type ContractOperation = 'read-own-wallet' | 'read-purchase-result' | 'authorise-purchase' | 'cancel-purchase' | 'provision-citizenship' | 'read-own-citizenship' | 'provision-organisation' | 'claim-founder-wallet' | 'make-commercial-payment' | 'make-citizen-transfer' | 'change-handle' | 'read-handle-change-receipt' | 'place-quote' | 'withdraw-quote' | 'request-buy-back' | 'read-citizen-market' | 'read-marketplace-receipt' | 'settle-marketplace-order' | 'settle-marketplace-refund' | 'present-standing-authorisation' | 'revoke-standing-authorisation' | 'bind-node';
 /**
  * An operation key belonging to a deployment's OWN surfaces rather than to this
  * contract — operator work, above all. Deliberately not enumerated: this package

package/dist/assurance.js

@@ -518,6 +518,41 @@ export const ASSURANCE_POLICY = {
             'bypass. Nothing moves when it is presented; what it authorises moves later, without the ' +
             'holder present, which is why the bar is applied here.',
     },
+    // The owner withdrawing that delegation from their Instance (CAY-0094). Held to the
+    // bar of the act it undoes: a credential that could not have delegated must not be
+    // able to withdraw a delegation either, or a weaker assertion becomes a way to stop
+    // an owner's Instance spending what they authorised.
+    'revoke-standing-authorisation': {
+        operation: 'revoke-standing-authorisation',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: 'Revoking a standing authorisation withdraws a delegation of spending from the ' +
+            "holder's wallet, so it is held to the bar of presenting one: anything but the " +
+            'development bypass. A credential that could not delegate cannot undo a delegation.',
+    },
+    // The owner's Instance binding a Node to their wallet (CMTY-0018 §4, CAY-0095). Held to
+    // the bar of presenting a standing authorisation: a bound Node's earnings are paid into
+    // the wallet at every later settlement, without the holder present, so choosing where
+    // they land is a decision about somebody's money.
+    'bind-node': {
+        operation: 'bind-node',
+        assurance: 'required',
+        decisions: {
+            // Asserts nothing; permanently refused wherever "identity-verified" is meant.
+            'dev-bypass': 'refused',
+            document: 'accepted',
+            'document-and-biometric': 'accepted',
+        },
+        rationale: "Binding a Node decides which wallet the Node's earnings are paid into at every later " +
+            'settlement, without the holder present, and a binding is never re-pointed, so it is ' +
+            'held to the bar of presenting a standing authorisation: anything but the development ' +
+            'bypass.',
+    },
 };
 /**
  * Every operation, as a value. Derived from {@link ASSURANCE_POLICY} for the same
@@ -559,6 +594,8 @@ export const OPERATION_FOR_ROUTE = {
     requestBuyBack: 'request-buy-back',
     marketplaceOrder: 'settle-marketplace-order',
     standingAuthorisation: 'present-standing-authorisation',
+    revokeStandingAuthorisation: 'revoke-standing-authorisation',
+    bindNode: 'bind-node',
     version: null,
 };
 /**

package/dist/client.d.ts

@@ -69,7 +69,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';
@@ -304,10 +304,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

@@ -309,6 +309,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,13 @@
  * 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 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).
+ *
  * ## What is not here
  *
  *   - **No Instance ID**, in any claim, row, request, answer or refusal (CAY-0059 §6).
@@ -79,14 +113,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 +231,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 +329,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 +705,70 @@ 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 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.
  */
-'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.