@zadq/x402 0.1.0 → 0.3.0

package/dist/holder/chain.d.ts

@@ -1,5 +1,7 @@
 /** The chain query path of the issuer-scoped read. */
 export declare const RECORDED_NULLIFIERS_QUERY = "/identity.v1.selfrevoke.Query/RecordedNullifiers";
+/** After how long the chain prunes a record (`retention_seconds`, both networks). */
+export declare const RECORD_RETENTION_SECONDS = 3600;
 /** A recorded self-revocation's state on the chain, by revocation value (hex). */
 export type RecordedState = 'pending' | 'folded';
 export type ChainReadOptions = {
@@ -12,7 +14,10 @@ export declare function bytesField(field: number, value: Uint8Array): Uint8Array
 export declare function varintField(field: number, value: number): Uint8Array;
 export declare function hexToBytes(hex: string): Uint8Array;
 export declare function bytesToHex(bytes: Uint8Array): string;
-/** `QueryRecordedNullifiersRequest{issuer_id = 1}` — names no revocation value. */
+/**
+ * `QueryRecordedNullifiersRequest{issuer_id = 1}` — `0a20‖issuer_id`; names
+ * no revocation value. The issuer id is exactly 32 bytes.
+ */
 export declare function encodeIssuerQuery(issuerIdHex: string): Uint8Array;
 /**
  * `QueryRecordedNullifiersResponse{repeated RecordedNullifier records = 1}`

package/dist/holder/chain.js

@@ -11,15 +11,25 @@
 // two protobuf shapes involved are small enough to encode and decode by
 // hand (varints and length-delimited fields only).
 //
-// CONTRACT POINT: the query path and the field numbers below
-// (request: issuer id = field 1; each record: version = 1, value = 2,
-// folded-in epoch = 3) are restated from MintID's chain query contract and
-// are to be confirmed against MintID's self-contained attachment on the
-// card that tracks this integration, before the first live run; they are
-// the only place to change.
+// The contract, as MintID delivered it on 2026-10-07 (the chain's
+// issuer-scoped recorded-revocations query, cited by name): service
+// `identity.v1.selfrevoke.Query`, method `RecordedNullifiers`, over CometBFT
+// `abci_query` with `prove: false` (no proven variant exists: the read is as
+// trustworthy as the node — run your own for more). Request
+// `{bytes issuer_id = 1}`, exactly 32 bytes, so `data` is `0a20‖issuer_id`;
+// the answer's `result.response.value` is base64 of
+// `{repeated RecordedNullifier records = 1; uint64 version = 2; uint64 acked = 3}`
+// with `RecordedNullifier{uint64 version = 1; bytes nullifier = 2;
+// uint64 folded_in_epoch = 3}` (0 while pending). Every unpruned record of
+// the issuer comes back; a record is pruned after `retention_seconds`
+// (3 600 s on both networks), so a value absent after it was seen is folded
+// and pruned, not lost. The chain's `Nullifier` query would
+// name the value to the node, and is not used here.
 import { HolderStepError } from "./errors.js";
 /** The chain query path of the issuer-scoped read. */
 export const RECORDED_NULLIFIERS_QUERY = '/identity.v1.selfrevoke.Query/RecordedNullifiers';
+/** After how long the chain prunes a record (`retention_seconds`, both networks). */
+export const RECORD_RETENTION_SECONDS = 3_600;
 function varint(value) {
     const out = [];
     let v = value;
@@ -46,9 +56,15 @@ export function hexToBytes(hex) {
 export function bytesToHex(bytes) {
     return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
 }
-/** `QueryRecordedNullifiersRequest{issuer_id = 1}` — names no revocation value. */
+/**
+ * `QueryRecordedNullifiersRequest{issuer_id = 1}` — `0a20‖issuer_id`; names
+ * no revocation value. The issuer id is exactly 32 bytes.
+ */
 export function encodeIssuerQuery(issuerIdHex) {
-    return bytesField(1, hexToBytes(issuerIdHex));
+    const id = hexToBytes(issuerIdHex);
+    if (id.length !== 32)
+        throw new HolderStepError('chain', 0, { error: 'issuer id is not 32 bytes' });
+    return bytesField(1, id);
 }
 function readVarint(data, pos) {
     let result = 0;

package/dist/holder/cli.d.ts

@@ -8,6 +8,8 @@ export declare const CUSTODY_KEY_ENV = "CREDENTIAL_CUSTODY_KEY";
 export declare const DASHBOARD_URL_ENV = "VERIFICATION_BASE_URL";
 export declare const DASHBOARD_SELLER_ENV = "VERIFICATION_SELLER_ID";
 export declare const DASHBOARD_SESSION_ENV = "VERIFICATION_SESSION";
+/** `--wait`: the fold grace and two root periods — the issuer has folded by then. */
+export declare const DEFAULT_WAIT_FOR_FOLD_MS: number;
 /** The credential state the seller's record takes at the dashboard service. */
 export declare const DASHBOARD_REVOKED_STATE = "self_revoked";
 export type KillSwitchEnv = Record<string, string | undefined>;

package/dist/holder/cli.js

@@ -14,20 +14,25 @@
 //
 // Flags: --yes (required: the revocation is irreversible), --no-jitter or
 // --jitter-ms <n> (the random delay before the submission, up to a minute
-// by default), --report (tell the dashboard, with VERIFICATION_BASE_URL,
+// by default), --wait or --wait-ms <n> (keep reading the chain after the
+// record shows, until the issuer has folded it: two minutes by default),
+// --report (tell the dashboard, with VERIFICATION_BASE_URL,
 // VERIFICATION_SELLER_ID and VERIFICATION_SESSION — the dashboard's short-lived session
 // credential — set). Nothing here logs; stdout carries the report only.
 import { pathToFileURL } from 'node:url';
+import { clientHeaders } from "../client.js";
 import { custodyKeyFromHex, fileCustodyStore, sealedCustodyStore, } from "./custody.js";
 import { HolderError } from "./errors.js";
 import { SellerHolder } from "./holder.js";
-import { CHAIN_ID_ENV, CHAIN_RPC_ENV, RELAY_URL_ENV, RelayRefusedError, revokeCredential, } from "./killswitch.js";
+import { CHAIN_ID_ENV, CHAIN_RPC_ENV, EFFECT_BOUND, RELAY_URL_ENV, RelayRefusedError, revokeCredential, } from "./killswitch.js";
 import { HOLDER_BINARY_ENV, HolderProcess } from "./process.js";
 export const CUSTODY_FILE_ENV = 'CREDENTIAL_CUSTODY_FILE';
 export const CUSTODY_KEY_ENV = 'CREDENTIAL_CUSTODY_KEY';
 export const DASHBOARD_URL_ENV = 'VERIFICATION_BASE_URL';
 export const DASHBOARD_SELLER_ENV = 'VERIFICATION_SELLER_ID';
 export const DASHBOARD_SESSION_ENV = 'VERIFICATION_SESSION';
+/** `--wait`: the fold grace and two root periods — the issuer has folded by then. */
+export const DEFAULT_WAIT_FOR_FOLD_MS = (EFFECT_BOUND.foldGraceSeconds + 2 * EFFECT_BOUND.rootPeriodSeconds) * 1000;
 /** The credential state the seller's record takes at the dashboard service. */
 export const DASHBOARD_REVOKED_STATE = 'self_revoked';
 const NEXT_STEP = 'Open the dashboard and press "Revoke my credential" → "My middleware revoked it" ' +
@@ -47,7 +52,8 @@ function value(argv, name) {
  */
 export async function runKillSwitch(argv, env, io, deps = {}) {
     if (!flag(argv, '--yes')) {
-        io.err('This revokes your credential for good: from the next status root on it presents nowhere, ' +
+        io.err('This revokes your credential for good: within ' +
+            `${EFFECT_BOUND.boundSeconds} s of the chain recording it, it presents nowhere, ` +
             'and only a new verification gives you a fresh one. Run again with --yes.');
         return 1;
     }
@@ -90,6 +96,17 @@ export async function runKillSwitch(argv, env, io, deps = {}) {
         }
         options.jitterMs = ms;
     }
+    if (flag(argv, '--wait'))
+        options.waitForFoldMs = DEFAULT_WAIT_FOR_FOLD_MS;
+    const wait = value(argv, '--wait-ms');
+    if (wait !== undefined) {
+        const ms = Number(wait);
+        if (!Number.isFinite(ms) || ms < 0) {
+            io.err('--wait-ms takes a non-negative number of milliseconds.');
+            return 1;
+        }
+        options.waitForFoldMs = ms;
+    }
     const rpc = deps.rpc ?? HolderProcess.start(env[HOLDER_BINARY_ENV]);
     const fetchImpl = deps.fetch ?? fetch;
     let report;
@@ -152,7 +169,11 @@ export async function reportToDashboard(fetchImpl, baseUrl, sellerId, session) {
     try {
         const response = await fetchImpl(`${baseUrl.replace(/\/+$/, '')}/v0/sellers/${encodeURIComponent(sellerId)}/credential`, {
             method: 'POST',
-            headers: { 'content-type': 'application/json', authorization: `Bearer ${session}` },
+            headers: {
+                ...clientHeaders(),
+                'content-type': 'application/json',
+                authorization: `Bearer ${session}`,
+            },
             body: JSON.stringify({ state: DASHBOARD_REVOKED_STATE }),
             signal: AbortSignal.timeout(15_000),
         });

package/dist/holder/holder.d.ts

@@ -106,6 +106,14 @@ export declare class SellerHolder {
     /** Forget the credential inside the process (its secret with it). The custody store is untouched. */
     close(): Promise<void>;
 }
+/**
+ * Reads a witness answer's `self_revoke_context` (issuer v1 witness route):
+ * the four anchoring members and `status_root`, which must name `root` —
+ * the root the witness was adopted on. `undefined` for `null`, for another
+ * root, or for anything not of that shape (the holder library would refuse
+ * it anyway; nothing is cached that cannot serve).
+ */
+export declare function readSelfRevokeContext(value: unknown, root: string): SelfRevokeMaterial | undefined;
 /**
  * Reads the verification service's `POST` body as an issued challenge:
  * `{request, signature_hex}`, or the bare request. Returns `undefined` for

package/dist/holder/holder.js

@@ -192,13 +192,10 @@ export class SellerHolder {
         });
         await this.persist();
         // The issuer serves the root's self-revocation material with the
-        // witness: keep it, only when it names the adopted root.
-        const material = body['self_revoke_context'];
-        if (typeof material === 'object' &&
-            material !== null &&
-            material['status_root'] === String(root.root)) {
-            this.material = material;
-        }
+        // witness (`self_revoke_context`, null unless usable and anchored on the
+        // served root). Cached at every refresh, for the adopted root only: a
+        // context for another root, or none, clears what an older refresh left.
+        this.material = readSelfRevokeContext(body['self_revoke_context'], String(root.root));
         return {
             status: state,
             usable: true,
@@ -304,26 +301,95 @@ export class SellerHolder {
      * primitive under it.
      */
     async selfRevoke(context) {
-        const anchoring = context.anchoring ?? this.material;
-        if (!anchoring) {
+        const given = context.anchoring ?? this.material;
+        if (!given) {
             throw new HolderError('no self-revocation material: refresh the witness first, or pass the issuer anchoring');
         }
+        // `anchoring` is `self_revoke_context` without `status_root`; the root
+        // travels beside it (optional for the library, checked against both
+        // witnesses when given).
+        const { status_root: servedRoot, ...anchoring } = given;
         const full = { chain_id: context.chain_id, anchoring };
-        const root = context.status_root ?? anchoring['status_root'];
+        const root = context.status_root ?? servedRoot;
         if (typeof root === 'string' && root !== '')
             full['status_root'] = root;
-        const out = (await this.rpc.call('self_revoke', {
-            holder: this.handle,
-            context: full,
-        }));
+        const out = await this.rpc.call('self_revoke', { holder: this.handle, context: full });
+        const revocation = readSelfRevocation(out);
         await this.persist();
-        return out;
+        return revocation;
     }
     /** Forget the credential inside the process (its secret with it). The custody store is untouched. */
     async close() {
         await this.rpc.call('drop', { holder: this.handle });
     }
 }
+const HEX = /^([0-9a-f]{2})*$/;
+const isHex = (v, bytes) => typeof v === 'string' && HEX.test(v) && (bytes === undefined || v.length === bytes * 2);
+function isLeafWitness(v) {
+    if (typeof v !== 'object' || v === null)
+        return false;
+    const w = v;
+    return (typeof w['status'] === 'string' &&
+        typeof w['status_epoch'] === 'number' &&
+        isHex(w['root']) &&
+        typeof w['index'] === 'number' &&
+        Array.isArray(w['path']) &&
+        w['path'].every((p) => isHex(p, 32)));
+}
+/**
+ * Reads a witness answer's `self_revoke_context` (issuer v1 witness route):
+ * the four anchoring members and `status_root`, which must name `root` —
+ * the root the witness was adopted on. `undefined` for `null`, for another
+ * root, or for anything not of that shape (the holder library would refuse
+ * it anyway; nothing is cached that cannot serve).
+ */
+export function readSelfRevokeContext(value, root) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const c = value;
+    const key = c['selfrevoke_encryption_key'];
+    if (c['status_root'] !== root ||
+        !isHex(c['issuer_definition']) ||
+        !isLeafWitness(c['definition_witness']) ||
+        !isLeafWitness(c['selfrevoke_encryption_key_witness']) ||
+        typeof key !== 'object' ||
+        key === null ||
+        typeof key['version'] !== 'number' ||
+        !isHex(key['public_key'], 48)) {
+        return undefined;
+    }
+    return value;
+}
+/**
+ * The library's `self_revoke` result as delivered: `{message (five
+ * fields), nullifier, ciphertext}`. `HolderError` on anything else — the
+ * holder has marked itself revoked by then, but nothing goes to a relay.
+ */
+function readSelfRevocation(out) {
+    const m = out['message'];
+    if (typeof m !== 'object' ||
+        m === null ||
+        !isHex(m['issuer_id'], 32) ||
+        !isHex(m['nullifier'], 32) ||
+        typeof m['status_epoch'] !== 'number' ||
+        !isHex(m['zk_authorization_proof']) ||
+        typeof m['proof_system_version'] !== 'string' ||
+        !isHex(out['nullifier'], 32) ||
+        typeof out['ciphertext'] !== 'string') {
+        throw new HolderError('the holder library answered self_revoke with an unexpected shape');
+    }
+    return {
+        message: {
+            issuer_id: m['issuer_id'],
+            nullifier: m['nullifier'],
+            status_epoch: m['status_epoch'],
+            zk_authorization_proof: m['zk_authorization_proof'],
+            proof_system_version: m['proof_system_version'],
+        },
+        nullifier: out['nullifier'],
+        ciphertext: out['ciphertext'],
+    };
+}
 /**
  * Reads the verification service's `POST` body as an issued challenge:
  * `{request, signature_hex}`, or the bare request. Returns `undefined` for

package/dist/holder/index.d.ts

@@ -1,8 +1,8 @@
 export { CredentialRevokedError, HolderError, HolderLibraryError, HolderStepError, OfferError, } from './errors.js';
-export { HOLDER_BINARY_ENV, HOLDER_PROTOCOL, HolderProcess, type HolderParams, type HolderRpc, } from './process.js';
+export { HOLDER_BINARY_ENV, HOLDER_PROTOCOL, HOLDER_RELEASE, HolderProcess, type HolderParams, type HolderRpc, } from './process.js';
 export { custodyKeyFromHex, fileCustodyStore, memoryCustodyStore, sealedCustodyStore, type CustodyKey, type CustodyStore, } from './custody.js';
-export { BUILD_INFO_PATH, CREDENTIAL_FORMAT, IDENTITY_CONFIGURATION_ID, METADATA_PATH, PRE_AUTHORIZED_GRANT, PRESENTATION_WINDOW_MS, PROOF_TYPE, SellerHolder, readCredentialOffer, readIssuedChallenge, type CredentialOffer, type Fetch, type HolderOptions, } from './holder.js';
-export type { ChallengeAnswer, ClaimPredicate, HolderInfo, IssuedChallenge, PresentationEnvelope, PresentationRequest, SelfRevocation, SelfRevokeContext, SelfRevokeMaterial, WitnessState, } from './types.js';
-export { CHAIN_ID_ENV, CHAIN_RPC_ENV, CONFIRM_ATTEMPTS, CONFIRM_INTERVAL_MS, DEFAULT_JITTER_MS, EFFECT_BOUND, RELAY_SUBMIT_PATH, RELAY_URL_ENV, RelayRefusedError, confirmSelfRevocation, revokeCredential, submitSelfRevocation, type Confirmation, type ConfirmOptions, type KillSwitchOptions, type KillSwitchReport, type RelayAnswer, type RelayOutcome, type SubmitOptions, } from './killswitch.js';
-export { RECORDED_NULLIFIERS_QUERY, decodeRecordedNullifiers, encodeIssuerQuery, readRecordedNullifiers, type ChainReadOptions, type RecordedState, } from './chain.js';
-export { CUSTODY_FILE_ENV, CUSTODY_KEY_ENV, DASHBOARD_REVOKED_STATE, DASHBOARD_SELLER_ENV, DASHBOARD_SESSION_ENV, DASHBOARD_URL_ENV, reportToDashboard, runKillSwitch, type CliReport, type KillSwitchDeps, type KillSwitchEnv, type KillSwitchIO, } from './cli.js';
+export { BUILD_INFO_PATH, CREDENTIAL_FORMAT, IDENTITY_CONFIGURATION_ID, METADATA_PATH, PRE_AUTHORIZED_GRANT, PRESENTATION_WINDOW_MS, PROOF_TYPE, SellerHolder, readCredentialOffer, readIssuedChallenge, readSelfRevokeContext, type CredentialOffer, type Fetch, type HolderOptions, } from './holder.js';
+export type { ChallengeAnswer, ClaimPredicate, HolderInfo, IssuedChallenge, PresentationEnvelope, PresentationRequest, AnchoredLeafWitness, SelfRevocation, SelfRevokeAnchoring, SelfRevokeContext, SelfRevokeMaterial, WitnessState, } from './types.js';
+export { AGENT_CREDENTIAL_REFUSAL, CHAIN_ID_ENV, CHAIN_RPC_ENV, CONFIRM_ATTEMPTS, CONFIRM_INTERVAL_MS, DEFAULT_JITTER_MS, DEFAULT_RELAY_ATTEMPTS, EFFECT_BOUND, MAX_RETRY_AFTER_MS, RELAY_API_VERSION, RELAY_BODY_CAP_BYTES, RELAY_REASON_CODES, RELAY_RETRY_AFTER_SECONDS, RELAY_SUBMIT_PATH, RELAY_UNREACHABLE_RETRY_SECONDS, RELAY_URL_ENV, RelayRefusedError, confirmSelfRevocation, isRelayReasonCode, revokeCredential, submitSelfRevocation, type ClientReasonCode, type Confirmation, type ConfirmOptions, type KillSwitchOptions, type KillSwitchReport, type RelayAnswer, type RelayOutcome, type RelayReasonCode, type SubmitOptions, } from './killswitch.js';
+export { RECORD_RETENTION_SECONDS, RECORDED_NULLIFIERS_QUERY, decodeRecordedNullifiers, encodeIssuerQuery, readRecordedNullifiers, type ChainReadOptions, type RecordedState, } from './chain.js';
+export { CUSTODY_FILE_ENV, CUSTODY_KEY_ENV, DASHBOARD_REVOKED_STATE, DASHBOARD_SELLER_ENV, DASHBOARD_SESSION_ENV, DASHBOARD_URL_ENV, DEFAULT_WAIT_FOR_FOLD_MS, reportToDashboard, runKillSwitch, type CliReport, type KillSwitchDeps, type KillSwitchEnv, type KillSwitchIO, } from './cli.js';

package/dist/holder/index.js

@@ -3,12 +3,12 @@
 // process. Node-only (it spawns the holder process); the rest of this
 // repository stays platform-neutral.
 export { CredentialRevokedError, HolderError, HolderLibraryError, HolderStepError, OfferError, } from "./errors.js";
-export { HOLDER_BINARY_ENV, HOLDER_PROTOCOL, HolderProcess, } from "./process.js";
+export { HOLDER_BINARY_ENV, HOLDER_PROTOCOL, HOLDER_RELEASE, HolderProcess, } from "./process.js";
 export { custodyKeyFromHex, fileCustodyStore, memoryCustodyStore, sealedCustodyStore, } from "./custody.js";
-export { BUILD_INFO_PATH, CREDENTIAL_FORMAT, IDENTITY_CONFIGURATION_ID, METADATA_PATH, PRE_AUTHORIZED_GRANT, PRESENTATION_WINDOW_MS, PROOF_TYPE, SellerHolder, readCredentialOffer, readIssuedChallenge, } from "./holder.js";
+export { BUILD_INFO_PATH, CREDENTIAL_FORMAT, IDENTITY_CONFIGURATION_ID, METADATA_PATH, PRE_AUTHORIZED_GRANT, PRESENTATION_WINDOW_MS, PROOF_TYPE, SellerHolder, readCredentialOffer, readIssuedChallenge, readSelfRevokeContext, } from "./holder.js";
 // The kill switch: self-revocation through the privacy relay, confirmed on
 // the chain, reported value-free (killswitch.ts); the issuer-scoped chain
 // read under it (chain.ts).
-export { CHAIN_ID_ENV, CHAIN_RPC_ENV, CONFIRM_ATTEMPTS, CONFIRM_INTERVAL_MS, DEFAULT_JITTER_MS, EFFECT_BOUND, RELAY_SUBMIT_PATH, RELAY_URL_ENV, RelayRefusedError, confirmSelfRevocation, revokeCredential, submitSelfRevocation, } from "./killswitch.js";
-export { RECORDED_NULLIFIERS_QUERY, decodeRecordedNullifiers, encodeIssuerQuery, readRecordedNullifiers, } from "./chain.js";
-export { CUSTODY_FILE_ENV, CUSTODY_KEY_ENV, DASHBOARD_REVOKED_STATE, DASHBOARD_SELLER_ENV, DASHBOARD_SESSION_ENV, DASHBOARD_URL_ENV, reportToDashboard, runKillSwitch, } from "./cli.js";
+export { AGENT_CREDENTIAL_REFUSAL, CHAIN_ID_ENV, CHAIN_RPC_ENV, CONFIRM_ATTEMPTS, CONFIRM_INTERVAL_MS, DEFAULT_JITTER_MS, DEFAULT_RELAY_ATTEMPTS, EFFECT_BOUND, MAX_RETRY_AFTER_MS, RELAY_API_VERSION, RELAY_BODY_CAP_BYTES, RELAY_REASON_CODES, RELAY_RETRY_AFTER_SECONDS, RELAY_SUBMIT_PATH, RELAY_UNREACHABLE_RETRY_SECONDS, RELAY_URL_ENV, RelayRefusedError, confirmSelfRevocation, isRelayReasonCode, revokeCredential, submitSelfRevocation, } from "./killswitch.js";
+export { RECORD_RETENTION_SECONDS, RECORDED_NULLIFIERS_QUERY, decodeRecordedNullifiers, encodeIssuerQuery, readRecordedNullifiers, } from "./chain.js";
+export { CUSTODY_FILE_ENV, CUSTODY_KEY_ENV, DASHBOARD_REVOKED_STATE, DASHBOARD_SELLER_ENV, DASHBOARD_SESSION_ENV, DASHBOARD_URL_ENV, DEFAULT_WAIT_FOR_FOLD_MS, reportToDashboard, runKillSwitch, } from "./cli.js";

package/dist/holder/killswitch.d.ts

@@ -5,27 +5,67 @@ import type { SelfRevocation } from './types.js';
 export type Fetch = typeof fetch;
 /** The relay's submission path (relay contract v0). */
 export declare const RELAY_SUBMIT_PATH = "/v1/self-revocations";
+/** The relay contract this module implements (`X-Relay-Api-Version` on every answer). */
+export declare const RELAY_API_VERSION = "0.1.0";
+/** The relay's body cap: 16 KiB. A larger body is refused here, before it travels. */
+export declare const RELAY_BODY_CAP_BYTES: number;
 /** Environment variables the middleware host is configured with. */
 export declare const RELAY_URL_ENV = "MINTID_RELAY_URL";
 export declare const CHAIN_RPC_ENV = "MINTID_CHAIN_RPC";
 export declare const CHAIN_ID_ENV = "MINTID_CHAIN_ID";
+/**
+ * The relay's closed reason vocabulary (relay contract v0 0.1.0): its own
+ * codes, the shape and lookup codes, the proof-check codes and the chain's
+ * `selfrevoke` codes (any other chain code arrives as `chain_refused`). An
+ * answer naming anything else is read as `unexpected_answer`.
+ */
+export declare const RELAY_REASON_CODES: readonly ["request_too_large", "malformed_json", "duplicate_submission", "busy", "chain_unavailable", "inclusion_timeout", "chain_refused", "proof_refused", "not_found", "method_not_allowed", "internal_error", "proof_system_version", "msg_shape", "nullifier", "nullifier_recorded", "unknown_root", "wire_version", "schema", "wire_shape", "path_depth", "anchor_definition", "anchor_encryption_key", "definition_shape", "encoding", "identity_point", "bbs_schnorr", "bbs_pairing", "acc_schnorr", "acc_pairing", "ve_c1", "ve_c2", "selfrevoke_disabled", "block_cap", "issuer_state", "issuer_cap", "pending_cap", "tx_shape", "params"];
+export type RelayReasonCode = (typeof RELAY_REASON_CODES)[number];
+/** True for a code of the relay's closed vocabulary. */
+export declare function isRelayReasonCode(value: unknown): value is RelayReasonCode;
+/**
+ * Codes decided on this side, never by the relay: the relay could not be
+ * reached, it answered outside its contract, or the message was refused
+ * before it left (`msg_shape`, `request_too_large` with stage `client`).
+ */
+export type ClientReasonCode = 'relay_unreachable' | 'unexpected_answer';
+/**
+ * The contract's `Retry-After` table, by code — used only when an answer
+ * that should carry the header does not (the header, when present, wins):
+ * `429 busy` 2 or 5 s, `503 chain_unavailable` 5 or 10 s, `503 block_cap` /
+ * `issuer_cap` 10 s, `503 busy` 10 s, `503 pending_cap` 60 s. The fallback
+ * takes the longer value of each row.
+ */
+export declare const RELAY_RETRY_AFTER_SECONDS: Readonly<Record<string, number>>;
+/** A relay that cannot be reached is tried again after this long. */
+export declare const RELAY_UNREACHABLE_RETRY_SECONDS = 5;
+/** The kill switch's submission attempts at one relay (the primitive's default is one). */
+export declare const DEFAULT_RELAY_ATTEMPTS = 3;
+/** No single wait is longer than the contract's longest `Retry-After` (pending_cap). */
+export declare const MAX_RETRY_AFTER_MS = 60000;
 /** A random delay before the revocation is built and sent: up to a minute by default. */
 export declare const DEFAULT_JITTER_MS = 60000;
 /** The confirmation read: about one block, in a few short reads. */
 export declare const CONFIRM_ATTEMPTS = 4;
 export declare const CONFIRM_INTERVAL_MS = 750;
 /**
- * The published effect bound, restated from the substrate's operational
- * rules: a status root every 30 s, a root accepted for at most 180 s (a
- * presentation against an older root is refused, so a recorded revocation
- * is effective everywhere within that bound once the issuer folds it at
- * its next root); a revoked principal's agents follow over the next roots,
- * about four minutes.
+ * The published effect bound (the network's revocation rule, per path; the
+ * same parameters on production and the public testnet): a holder
+ * self-revocation — the kill switch — is effective everywhere within
+ * G + A + K = 245 s of the chain recording it (fold grace 60 s, a root
+ * accepted for at most 180 s, 5 s of future skew; a root every 30 s). A
+ * revoked principal's agents follow within 7·H + A + K = 395 s of the root
+ * that carries the trigger. The bound is the guarantee: a measured figure
+ * is only ever quoted next to it.
  */
 export declare const EFFECT_BOUND: {
-    readonly statusRootSeconds: 30;
-    readonly rootAcceptedSeconds: 180;
-    readonly agentCascadeSeconds: 240;
+    readonly boundSeconds: 245;
+    readonly countedFrom: "recorded_on_chain";
+    readonly principalCascadeSeconds: 395;
+    readonly rootPeriodSeconds: 30;
+    readonly acceptanceWindowSeconds: 180;
+    readonly futureSkewSeconds: 5;
+    readonly foldGraceSeconds: 60;
 };
 /** What the relay answered, in the contract's own words. */
 export type RelayOutcome = 'recorded' | 'queued' | 'inclusion_timeout' | 'nullifier_recorded' | 'duplicate_submission';
@@ -33,29 +73,38 @@ export type RelayAnswer = {
     outcome: RelayOutcome;
     txHash?: string;
     height?: number;
+    /** What the relay says the chain holds (200 only) — never the receipt: the chain read decides. */
+    relayNullifierState?: RecordedState;
 };
-/** A relay refusal: the contract's bare reason code and stage, nothing of the message. */
+/** A relay refusal: the bare reason code and stage, nothing of the message. */
 export declare class RelayRefusedError extends HolderError {
     readonly status: number;
-    readonly code: string;
-    readonly stage: string;
-    /** Worth a retry, here or at another relay (`busy`, `chain_unavailable`, caps). */
+    readonly code: RelayReasonCode | ClientReasonCode;
+    /** `client`: decided on this side (unreachable, outside the contract, refused before sending). */
+    readonly stage: 'relay' | 'precheck' | 'chain' | 'client';
+    /** Worth a retry, here or at another relay (`busy`, `chain_unavailable`, caps, unreachable). */
     readonly retryable: boolean;
     readonly retryAfterMs: number | undefined;
-    constructor(status: number, code: string, stage: string, retryAfterMs?: number);
+    constructor(status: number, code: RelayReasonCode | ClientReasonCode, stage: 'relay' | 'precheck' | 'chain' | 'client', retryAfterMs?: number);
 }
 export type SubmitOptions = {
     /** The relay's own transport — never the holder's issuer transport. */
     fetch?: Fetch;
     timeoutMs?: number;
+    /** Attempts at this relay; a retryable refusal waits its `Retry-After` first. Default 1. */
+    attempts?: number;
+    sleep?: (ms: number) => Promise<void>;
 };
 /**
  * Hands the self-revocation to the privacy relay: `{message}` with the five
  * message fields only, no header beyond the content type. The relay checks
- * the proof with the chain's rules, pays for the transaction and submits
- * it; this side signs nothing and holds no account. `RelayRefusedError` on
- * a refusal; every accepted answer (recorded, queued, already recorded,
- * already in flight, broadcast but not yet seen) still needs the chain read.
+ * the proof against the issuer's anchored root, pays for the transaction
+ * and submits it; this side signs nothing and holds no account.
+ * `RelayRefusedError` on a refusal (the code from the closed vocabulary);
+ * every accepted answer (recorded, queued, already recorded, already in
+ * flight, broadcast but not yet seen) still needs the chain read. With
+ * `attempts` above one, a retryable refusal (429, 503, unreachable) is
+ * tried again after the relay's `Retry-After` (or the contract's table).
  */
 export declare function submitSelfRevocation(relayUrl: string, revocation: SelfRevocation, options?: SubmitOptions): Promise<RelayAnswer>;
 export type ConfirmOptions = {
@@ -64,31 +113,45 @@ export type ConfirmOptions = {
     attempts?: number;
     intervalMs?: number;
     sleep?: (ms: number) => Promise<void>;
+    /**
+     * `recorded` (default): stop at the first read that shows the record.
+     * `folded`: keep reading while it is pending, until folded or the
+     * attempts run out (the report is then `pending`).
+     */
+    until?: 'recorded' | 'folded';
+    /**
+     * What an earlier read showed for this revocation. A value seen once and
+     * absent now has been folded and pruned (the chain keeps a record for
+     * `RECORD_RETENTION_SECONDS`), so it reads `folded`.
+     */
+    seen?: RecordedState;
 };
 export type Confirmation = {
     state: RecordedState;
+    pruned?: true;
 } | {
     state: 'unconfirmed';
     reason: 'no_chain_endpoint' | 'chain_unreachable' | 'not_recorded';
 };
 /**
- * Asks a node of the chain whether the revocation is there — for about one
- * block — reading the issuer's recorded set and finding the holder's own
- * value locally, so the node never learns which one. `pending` once
- * recorded, `folded` once the issuer's next root has folded it; otherwise
- * `unconfirmed` with the reason (no node named, node unreachable, not
- * recorded yet).
+ * Asks a node of the chain whether the revocation is there, reading the
+ * issuer's recorded set and finding the holder's own value locally, so the
+ * node never learns which one. `pending` once recorded, `folded` once the
+ * issuer has folded it (or, after an earlier sighting, once the chain has
+ * pruned it); otherwise `unconfirmed` with the reason (no node named, node
+ * unreachable, not recorded yet). The relay's answer never enters here.
  */
 export declare function confirmSelfRevocation(rpcUrl: string | undefined, revocation: SelfRevocation, options?: ConfirmOptions): Promise<Confirmation>;
 /** What the kill switch reports to the seller — value-free. */
 export type KillSwitchReport = {
     /**
-     * `revoked`: the chain holds the record and the issuer has folded it —
-     * the credential presents nowhere. `pending`: the chain holds the record;
-     * it lands at the issuer's next root, within the bound. `unconfirmed`:
-     * the relay accepted the submission but no node showed the record within
-     * the read window (or none was named) — check again, or resubmit through
-     * a relay; both are safe.
+     * `revoked`: the chain holds the record and the issuer has folded it.
+     * `pending`: the chain holds the record and the issuer folds it at a next
+     * root. Either way the credential is refused everywhere within the
+     * published bound (`effect`, 245 s from the record). `unconfirmed`: the
+     * relay accepted the submission but no node showed the record within the
+     * read window (or none was named) — check again, or resubmit through a
+     * relay; both are safe.
      */
     state: 'revoked' | 'pending' | 'unconfirmed';
     relay: RelayOutcome;
@@ -98,6 +161,7 @@ export type KillSwitchReport = {
     height?: number;
     /** The holder refuses to present from now on, whatever the chain shows. */
     holderRefusesToPresent: true;
+    /** The published bound — the guarantee; never a measured figure. */
     effect: typeof EFFECT_BOUND;
 };
 export type KillSwitchOptions = {
@@ -109,31 +173,50 @@ export type KillSwitchOptions = {
     /** The relay's transport; the chain read's transport. Neither is the issuer's. */
     relayFetch?: Fetch;
     chainFetch?: Fetch;
+    /** Submission attempts at the relay, `Retry-After` honoured between them (default 3). */
+    relayAttempts?: number;
     confirmAttempts?: number;
     confirmIntervalMs?: number;
+    /**
+     * Keep reading after the record shows, until the issuer has folded it,
+     * for up to this long (0, the default: report at the first sighting).
+     */
+    waitForFoldMs?: number;
     sleep?: (ms: number) => Promise<void>;
     /** Uniform in [0, 1); injected by tests. */
     random?: () => number;
 };
+/**
+ * What the seller path answers for an agent credential: agent credentials
+ * are revoked through the verification service's agent kill route (the
+ * operator console's kill action), which keeps the operator view's state —
+ * never through this path.
+ */
+export declare const AGENT_CREDENTIAL_REFUSAL: string;
 /**
  * The product kill switch, end to end, where the key is:
  *
  * 1. a random delay, so the moment the seller decided is not the moment
- *    the chain records (the relay shuffles what it holds; this adds the
- *    seller's own slack);
- * 2. a fresh witness from the issuer, so the self-revocation is built
- *    against the root the chain currently holds (the material comes with
- *    the witness answer; no other call);
- * 3. the self-revocation, built by the holder library — from that moment
- *    the holder refuses to present, also after a reload from custody;
- * 4. the submission through the privacy relay; a refusal for a root the
- *    chain no longer holds rebuilds against the current one, once;
- * 5. the confirmation read on the chain, issuer-scoped.
+ *    the chain records (the relay adds its own 0–6 s and shuffles each
+ *    block's batch; this adds the seller's slack);
+ * 2. a fresh witness from the issuer, whose answer carries the root's
+ *    `self_revoke_context` (no other call);
+ * 3. the holder library's `self_revoke` — `context = {chain_id,
+ *    status_root, anchoring}` with `anchoring` the served context without
+ *    `status_root` — and from that moment the holder refuses to present,
+ *    also after a reload from custody;
+ * 4. the submission through the privacy relay, `Retry-After` honoured; a
+ *    refusal for a root the chain no longer holds (`unknown_root`)
+ *    rebuilds the context once from a fresh witness;
+ * 5. the confirmation read on the chain, issuer-scoped — the relay's
+ *    answer is never the receipt.
  *
- * Configuration: `relayUrl` (or `MINTID_RELAY_URL`), `chainRpc` (or
- * `MINTID_CHAIN_RPC`; without it the report is `unconfirmed`,
- * `no_chain_endpoint`), `chainId` (or `MINTID_CHAIN_ID`, else the issuer's
- * public build information). The client never bypasses the relay to the
- * chain: it holds no account and signs nothing.
+ * The seller's own credential only: an agent credential is refused
+ * (`AGENT_CREDENTIAL_REFUSAL`). Configuration: `relayUrl` (or
+ * `MINTID_RELAY_URL`), `chainRpc` (or `MINTID_CHAIN_RPC`; without it the
+ * report is `unconfirmed`, `no_chain_endpoint`), `chainId` (or
+ * `MINTID_CHAIN_ID`, else the issuer's public build information). The
+ * client never bypasses the relay to the chain: it holds no account and
+ * signs nothing.
  */
 export declare function revokeCredential(holder: SellerHolder, options?: KillSwitchOptions): Promise<KillSwitchReport>;