@percayso-community/cayso-contracts 0.27.0 → 0.30.0

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.