@percayso-community/cayso-contracts 0.24.0 → 0.27.0

package/dist/cloud-settlement.d.ts

@@ -0,0 +1,460 @@
+/**
+ * `cloud-settlement` — the Percayso Cloud's two seams with Cayso: the **standing
+ * authorisation** an Instance presents and Cayso acknowledges, and the **settlement
+ * 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.
+ *
+ * ## Two seams, two authorities
+ *
+ * **The standing authorisation** is an owner delegating spending: one signed act,
+ * on a passkey ceremony, allowing their Instance to spend up to a cap per
+ * settlement period on Percayso Cloud services. The Instance presents it under the
+ * owner's assertion (`present-standing-authorisation`, `ROUTES.standingAuthorisation`),
+ * which is money-grade in `ASSURANCE_POLICY`, so `dev-bypass` is never admissible.
+ * Cayso answers with an {@link AuthorisationAcknowledgementClaims}, signed by a
+ * 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 settlement assertion** is the Contribution Store's statement of one
+ * period: contribution by Node, consumption by authorisation. It is presented by
+ * the Store directly, authenticated by a registered Store issuer (CAY-0030) and
+ * not by a person, so its path is {@link CLOUD_SETTLEMENT_ROUTE} and never an entry
+ * in `ROUTES`, whose every entry is classified by a person's assurance.
+ *
+ * Both documents and the acknowledgement are compact assertions in CAY-0072's
+ * format: three unpadded base64url segments, a header of exactly `alg` and `kid`,
+ * the signature over the bytes that travelled, and `iat` and `exp` in **seconds**.
+ * This module types the claims; the request carries the compact string exactly as
+ * signed, and Cayso reads nothing from it as a fact until it has verified it.
+ *
+ * ## Where this departs from CMTY-0018: no Instance ID crosses
+ *
+ * CMTY-0018 puts an Instance ID in all three documents. **Cayso records no
+ * Instance ID in any role** (CAY-0059 §6), and the pillar owner kept that rule
+ * unamended on 5 October 2026. So the spender is identified by two things that
+ * already exist and say nothing about where an Instance runs:
+ *
+ *   - the **authorisation's `jti`**, unique per authorisation, which every
+ *     consumption row cites; and
+ *   - the **Instance key's `kid`** ({@link InstanceKeyId}), a pseudonymous key id.
+ *
+ * A {@link StandingAuthorisationClaims}' `iss` and `sub` are that `kid`; the
+ * acknowledgement carries the authorisation's `jti` and the `kid`; a consumption
+ * row is keyed by the authorisation's `jti` alone. The Cloud still meters by
+ * Instance ID on its own side, and that never crosses to Cayso. CMTY-0018 is a
+ * Community record, so the change is Cayso's to request rather than to make: an
+ * amendment request goes to community.documentation, and until it lands this
+ * package, not the record, is the shape the Cloud generates from (CAY-0026,
+ * Amendment 3).
+ *
+ * ## Fail closed on the whole assertion
+ *
+ * A settlement assertion is settled whole or not at all (CAY-0021, CMTY-0018 §2).
+ * A refused one is a dispute between the two pillars, raised to a person: never
+ * partially settled, never silently corrected on either side. The refusal names
+ * the first reason, and, when the reason is about a row, which row
+ * ({@link ContributionRowRefused}, {@link ConsumptionRowRefused}). "First" is a
+ * fixed order: the assertion as a whole, then the contribution leg in the order
+ * it was signed, then the consumption leg in the order it was signed.
+ *
+ * The same assertion presented twice is a no-op (CAY-0023): its `jti` is the
+ * period's id and the idempotency key, and a replay answers what the first
+ * presentation answered.
+ *
+ * ## What is not here
+ *
+ *   - **No Instance ID**, in any claim, row, request, answer or refusal (CAY-0059 §6).
+ *   - **No wallet, account or Citizen** in anything Cayso signs for the Cloud, nor
+ *     in anything the Store signs for Cayso. Cayso resolves a Node and a key to a
+ *     wallet on its own side, in the Trust Network (CAY-0006).
+ *   - **No Percayso identity** (CAY-0006). The owner's assertion authenticates the
+ *     presentation; its subject is never a claim here.
+ *   - **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
+ *     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.
+ *   - **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.
+ */
+import type { Cents } from './wallet.js';
+/**
+ * The id of one Instance key: the RFC 7638 SHA-256 thumbprint of its public half,
+ * unpadded base64url. Derived rather than minted, so a key id cannot be re-pointed
+ * at a different key, and pseudonymous, so it says nothing about where the
+ * Instance runs (CAY-0059 §6). Opaque to a consumer: compare it, never parse it.
+ */
+export type InstanceKeyId = string;
+/**
+ * Which period rule a cap is per: an opaque identifier of the rule Cayso publishes.
+ * Its value, and the rule's length, are the canon's and are not set here
+ * (CMTY-0018 §1, community.documentation#24).
+ */
+export type SettlementPeriodRule = string;
+/** One settlement period's id, made by the period rule. Opaque here. */
+export type SettlementPeriodId = string;
+/** A Node's id, as the Cloud's Node Registry holds it. Never an account. */
+export type NodeId = string;
+/**
+ * The Contribution Store's issuer id, one per environment, so an assertion signed
+ * for one environment can never settle on another's ledger (CMTY-0018 §2). Closed:
+ * an environment this union does not name is not one the Store signs for.
+ */
+export type ContributionStoreIssuer = 'percayso-cloud-store:dev' | 'percayso-cloud-store:stage' | 'percayso-cloud-store:main';
+/** The audience of a standing authorisation and of its acknowledgement. */
+export type PercaysoCloudAudience = 'percayso-cloud';
+/**
+ * The owner's act: one signed authorisation, made in their Instance on a passkey
+ * ceremony, allowing that Instance to spend up to `cap_cents` per settlement
+ * period on Percayso Cloud services (CMTY-0018 §1). Signed by the Instance key, in
+ * CAY-0072's format, whose header `kid` is `iss`.
+ */
+export interface StandingAuthorisationClaims {
+    /** The Instance key that signed it. The same value as `sub` and the header's `kid`. */
+    readonly iss: InstanceKeyId;
+    /** The spender: the same Instance key, because the authoriser and the spender are one Instance. */
+    readonly sub: InstanceKeyId;
+    /** Exactly `'percayso-cloud'`, and checked, not merely present. */
+    readonly aud: PercaysoCloudAudience;
+    /** The most the Instance may spend on Percayso Cloud services in one period, in whole cents. */
+    readonly cap_cents: Cents;
+    /** The period rule the cap is per. Opaque; the canon sets its value. */
+    readonly period: SettlementPeriodRule;
+    /** Issued-at, in **seconds** since the Unix epoch. */
+    readonly iat: number;
+    /**
+     * Expiry, in **seconds** since the Unix epoch. The owner's choice, bounded by a
+     * canon figure. An authorisation outlives many periods.
+     */
+    readonly exp: number;
+    /** The authorisation's own id, unique, which every consumption row later cites. */
+    readonly jti: string;
+}
+/**
+ * The Instance presenting its owner's standing authorisation, under the owner's
+ * assertion (`present-standing-authorisation`).
+ */
+export interface StandingAuthorisationRequest {
+    /** The compact {@link StandingAuthorisationClaims}, exactly as the Instance key signed it. */
+    readonly standingAuthorisation: string;
+    /**
+     * The Instance key's public half, as the JSON text of a public JSON Web Key. Its
+     * RFC 7638 thumbprint must be the authorisation's `kid`, so the key that verifies
+     * the authorisation is the key it names, and no other.
+     */
+    readonly instanceKey: string;
+}
+/**
+ * Cayso's act: the acknowledgement that it holds a standing authorisation for this
+ * Instance key, signed by a Cayso issuer key in CAY-0072's format (CMTY-0018 §1).
+ * The Cloud verifies it against the one Cayso issuer in its registry and meters
+ * against it. It carries no wallet, no account, no Citizen and no Instance ID.
+ *
+ * It expires at the end of the period after the one it was issued in, so a
+ * revocation reaches the Cloud within one period without the Cloud asking Cayso
+ * anything on the request path.
+ */
+export interface AuthorisationAcknowledgementClaims {
+    /** The Cayso issuer that signed it. */
+    readonly iss: string;
+    /** Exactly `'percayso-cloud'`. */
+    readonly aud: PercaysoCloudAudience;
+    /** The acknowledged authorisation's `jti`. */
+    readonly authorisation: string;
+    /**
+     * The Instance key the authorisation was signed with, which the Cloud verifies
+     * every request from this Instance against. Not the header's `kid`, which names
+     * Cayso's signing key.
+     */
+    readonly instance_kid: InstanceKeyId;
+    /** The cap, as the authorisation stated it, in whole cents. */
+    readonly cap_cents: Cents;
+    /** The period rule, as the authorisation stated it. */
+    readonly period: SettlementPeriodRule;
+    /** Issued-at, in **seconds** since the Unix epoch. */
+    readonly iat: number;
+    /** Expiry, in **seconds** since the Unix epoch. */
+    readonly exp: number;
+}
+/** Cayso holds the authorisation, and here is its acknowledgement for the Cloud. */
+export interface StandingAuthorisationAcknowledged {
+    readonly outcome: 'acknowledged';
+    /** The compact {@link AuthorisationAcknowledgementClaims}, signed by Cayso. Carried, never edited. */
+    readonly acknowledgement: string;
+}
+/** The authorisation was refused, with one member of the closed union. Nothing was bound. */
+export interface StandingAuthorisationRefused {
+    readonly outcome: 'refused';
+    readonly error: StandingAuthorisationRefusal;
+}
+/**
+ * The ONE declared answer to `present-standing-authorisation`, discriminated by
+ * `outcome`. A consumer switches on `outcome` and never sniffs which fields are
+ * present.
+ */
+export type StandingAuthorisationResponse = StandingAuthorisationAcknowledged | StandingAuthorisationRefused;
+/**
+ * Why a standing authorisation was refused. Closed: a consumer renders a member by
+ * its name and never pattern-matches on prose, and a new reason is a new member
+ * and a contract version. Every member means the same thing: nothing was bound and
+ * no acknowledgement was signed.
+ */
+export type StandingAuthorisationRefusal = 
+/**
+ * The verification method is outside the money-grade assurance profile
+ * (`ASSURANCE_POLICY['present-standing-authorisation']`). `dev-bypass` is never
+ * inside it.
+ */
+'assurance_not_money_grade'
+/** No wallet is bound to the verified holder now, so there is no wallet to spend from. */
+ | 'wallet_has_no_live_binding'
+/**
+ * Not a compact assertion in CAY-0072's format, or its claims are not exactly the
+ * closed set of {@link StandingAuthorisationClaims}.
+ */
+ | 'authorisation_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 authorisation's `kid`. */
+ | 'instance_key_not_the_kid'
+/** The signature does not verify over the bytes presented. */
+ | 'authorisation_signature_invalid'
+/** `iss` or `sub` is not the key that signed it: the authoriser and the spender are one Instance key. */
+ | 'authorisation_not_signed_by_its_spender'
+/** `aud` is not `'percayso-cloud'`. */
+ | 'authorisation_audience_wrong'
+/** `exp` is at or before now. */
+ | 'authorisation_expired'
+/** `iat` is further ahead of now than the clock-skew tolerance. */
+ | 'authorisation_issued_in_the_future'
+/** `exp` is further ahead than the canon's longest authorisation allows. */
+ | 'authorisation_outlives_its_ceiling'
+/** `period` names no period rule Cayso publishes. */
+ | 'settlement_period_rule_not_recognised'
+/**
+ * The `jti` was already presented with different claims. Two authorisations cannot
+ * share the id every consumption row cites, so neither is answered.
+ */
+ | 'authorisation_jti_reused_for_a_different_authorisation'
+/** The owner revoked this authorisation. It is never acknowledged again. */
+ | 'authorisation_revoked'
+/** The cap is more than this holder may delegate. */
+ | '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 kind of contribution a row measures: the three of the Community map's #3. Closed. */
+export type ContributionType = 'storage' | 'compute' | 'full-node';
+/**
+ * The period a settlement assertion settles: its id, made by the period rule, and
+ * the UTC instants that bound it, in **seconds** since the Unix epoch. Block height
+ * replaces the instants as the ordering clock once there is a chain (CAY-0006).
+ */
+export interface SettlementPeriod {
+    readonly id: SettlementPeriodId;
+    readonly starts_at: number;
+    readonly ends_at: number;
+}
+/** Why a contribution row is withheld rather than paid. Earnings withheld are not lost. */
+export type ContributionWithheldReason = 
+/** The Node is bound to no wallet yet (CMTY-0018 §4). */
+'node_not_bound'
+/** The Node did not pass its ladder gate this period. */
+ | 'ladder_gate_not_passed';
+/** The row passed its ladder gate, and its amount is payable. */
+export interface ContributionQualified {
+    readonly gate: 'passed';
+    /** The Node's ladder position, as the Cloud names it. Opaque here. */
+    readonly position: string;
+}
+/** The row is carried and its amount withheld, with the reason. */
+export interface ContributionWithheld {
+    readonly gate: 'withheld';
+    /** The Node's ladder position, as the Cloud names it. Opaque here. */
+    readonly position: string;
+    readonly reason: ContributionWithheldReason;
+}
+/**
+ * Whether a row qualified. A union rather than a flag and an optional reason, so a
+ * withheld row without a reason, or a qualified row with one, is not expressible.
+ */
+export type ContributionQualification = ContributionQualified | ContributionWithheld;
+/**
+ * One contribution row: one Node and one contribution type, measured on the Core
+ * side by the challenger and the gateway, never as the Node reported it.
+ */
+export interface ContributionRow {
+    readonly node_id: NodeId;
+    readonly type: ContributionType;
+    /** How much was contributed, in `unit`s. */
+    readonly quantity: number;
+    /** What `quantity` counts, for example GB-hours held and proved. Open. */
+    readonly unit: string;
+    /** The fraction of the availability contract delivered, from nought to one. */
+    readonly fulfilment: number;
+    readonly qualified: ContributionQualification;
+    /** What the Store calculated under the rate of the Node's contract, in whole cents. */
+    readonly amount_cents: Cents;
+}
+/**
+ * One consumption row: one authorisation and one service, metered by the gateway
+ * and the storage rendezvous. Keyed by the authorisation's `jti` alone, never by an
+ * Instance ID (CAY-0059 §6).
+ */
+export interface ConsumptionRow {
+    /** The `jti` of the standing authorisation this consumption was metered against. */
+    readonly authorisation: string;
+    /** The service consumed, for example inference or storage. Open. */
+    readonly service: string;
+    /** How much was consumed, in `unit`s. */
+    readonly quantity: number;
+    /** What `quantity` counts. Open. */
+    readonly unit: string;
+    readonly amount_cents: Cents;
+    /** The cap as the acknowledgement stated it, so Cayso can see the Cloud stayed inside it. */
+    readonly cap_cents: Cents;
+}
+/** The sums of both legs, so a verifier refuses a row set that does not add before reading it. */
+export interface SettlementTotals {
+    readonly contribution_cents: Cents;
+    readonly consumption_cents: Cents;
+}
+/**
+ * One period's settlement, signed by the Contribution Store with a key whose public
+ * half is a registered Cayso issuer under its own `kid` (CAY-0030), in CAY-0072's
+ * format (CMTY-0018 §2). One per period per environment.
+ */
+export interface SettlementAssertionClaims {
+    readonly iss: ContributionStoreIssuer;
+    /** Exactly `'cayso'`. */
+    readonly aud: 'cayso';
+    readonly period: SettlementPeriod;
+    /**
+     * The hash over the period's rows in the Store. Opaque here: how it is made, and
+     * who writes it to the chain, are community.documentation#24's.
+     */
+    readonly commitment: string;
+    readonly contribution: readonly ContributionRow[];
+    readonly consumption: readonly ConsumptionRow[];
+    readonly totals: SettlementTotals;
+    /** The period's id, and the idempotency key: the same assertion presented twice is a no-op. */
+    readonly jti: string;
+    /** Issued-at, in **seconds** since the Unix epoch. */
+    readonly iat: number;
+    /** Expiry, in **seconds** since the Unix epoch. */
+    readonly exp: number;
+}
+/**
+ * The Contribution Store presenting one period's settlement assertion, under its
+ * own registered issuer and no person's assertion.
+ */
+export interface SettlementAssertionRequest {
+    /** The compact {@link SettlementAssertionClaims}, exactly as the Store signed it. */
+    readonly settlementAssertion: string;
+}
+/**
+ * The period was settled whole. Answered for the presentation that settled it and
+ * for every replay of the same assertion, in the same shape.
+ */
+export interface SettlementAssertionSettled {
+    readonly outcome: 'settled';
+    /** The settled assertion's `jti`: the period's id. */
+    readonly jti: string;
+}
+/** The assertion as a whole was refused. No row is named, because none was read as a fact. */
+export interface SettlementAssertionRefused {
+    readonly outcome: 'refused';
+    readonly error: SettlementAssertionLevelRefusal;
+    readonly leg: null;
+    readonly row: null;
+}
+/** The first failing row is on the contribution leg. Nothing was settled. */
+export interface ContributionRowRefused {
+    readonly outcome: 'refused';
+    readonly error: ContributionRowRefusal;
+    readonly leg: 'contribution';
+    /** The row's zero-based position in the contribution leg as signed. */
+    readonly row: number;
+}
+/** The first failing row is on the consumption leg. Nothing was settled. */
+export interface ConsumptionRowRefused {
+    readonly outcome: 'refused';
+    readonly error: ConsumptionRowRefusal;
+    readonly leg: 'consumption';
+    /** The row's zero-based position in the consumption leg as signed. */
+    readonly row: number;
+}
+/**
+ * The ONE declared answer to a settlement assertion, discriminated by `outcome`,
+ * and a refusal by `leg`. A row reason always names its row and an assertion
+ * reason never does: the pairing is in the types, not in care.
+ */
+export type SettlementAssertionResponse = SettlementAssertionSettled | SettlementAssertionRefused | ContributionRowRefused | ConsumptionRowRefused;
+/**
+ * Why a settlement assertion was refused as a whole, before any row was read as a
+ * fact.
+ */
+export type SettlementAssertionLevelRefusal = 
+/**
+ * Not a compact assertion in CAY-0072's format, or its claims are not exactly the
+ * closed set of {@link SettlementAssertionClaims}.
+ */
+'settlement_malformed'
+/** `iss` is not a Store issuer this deployment's registry holds, or the `kid` is not one of its keys. */
+ | 'settlement_issuer_not_recognised'
+/**
+ * `iss` names a Store issuer of another environment. A DEV assertion never
+ * settles on a MAIN ledger, and neither does any other pairing.
+ */
+ | 'settlement_issuer_for_another_environment'
+/** The signature does not verify over the bytes presented. */
+ | 'settlement_signature_invalid'
+/** `aud` is not `'cayso'`. */
+ | 'settlement_audience_wrong'
+/** `exp` is at or before now. */
+ | 'settlement_expired'
+/** `iat` is further ahead of now than the clock-skew tolerance. */
+ | 'settlement_issued_in_the_future'
+/** `jti` is not the period's id. */
+ | 'settlement_jti_not_the_period'
+/**
+ * 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';
+/** 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.
+ */
+'contribution_node_not_bound';
+/** 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. */
+ | 'consumption_authorisation_revoked'
+/** The row's cap is not the cap the acknowledgement stated. */
+ | 'consumption_cap_not_the_acknowledged_cap'
+/** The authorisation's running total in this period passes its cap at this row. */
+ | 'consumption_over_cap';
+/**
+ * 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.
+ */
+export type SettlementAssertionRefusal = SettlementAssertionLevelRefusal | ContributionRowRefusal | ConsumptionRowRefusal;

package/dist/cloud-settlement.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/contract-schema.generated.d.ts

@@ -2,7 +2,8 @@
  * GENERATED FILE — do not edit by hand.
  *
  * Produced by `scripts/generate-contract-schema.ts` from the published types
- * (`wallet.ts`, `purchase.ts`, `assertion.ts`, `citizenship.ts`, `errors.ts`)
+ * (`wallet.ts`, `purchase.ts`, `assertion.ts`, `citizenship.ts`, `errors.ts`
+ * and the rest of the barrel's surface, with `operator.ts` under its own key)
  * and the
  * package's own value exports. Regenerate with `pnpm --filter @percayso-community/cayso-contracts generate-schema`.
  *