@cinchor/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,514 @@
+import { ContractQueryResult, AbiArgument } from '@omne/sdk';
+
+/**
+ * @cinchor/sdk — connection + deployment configuration.
+ *
+ * Everything that ties the SDK to a specific network and a specific deployed
+ * accountability contract is injected here, not hardcoded. A consumer points
+ * the SDK at their target network (devnet, testnet, mainnet) and the address of
+ * the deployed contract they were given.
+ */
+/** Network coordinates the SDK talks to. */
+interface NetworkConfig {
+    /** Human-readable network name (informational). */
+    name: string;
+    /** Omne chain id (Ignis devnet = 3). Signed into every transaction. */
+    chainId: number;
+    /** JSON-RPC endpoint URL. */
+    rpcUrl: string;
+}
+/**
+ * The deployed accountability contract the SDK calls.
+ *
+ * `name` is the on-chain contract module name; the runtime resolves calls via
+ * the full export path `axiom_contract::<name>::<function>`, which `exportPrefix`
+ * encodes. These are deployment details, not brand surfaces — point them at
+ * whatever contract instance you were given.
+ */
+interface ContractConfig {
+    /** On-chain contract module name. */
+    name: string;
+    /** Deployed contract address (om1z bech32m). */
+    address: string;
+    /** Runtime export prefix: `axiom_contract::<name>::`. Derived if omitted. */
+    exportPrefix?: string;
+}
+/** Full SDK configuration. */
+interface CinchorConfig {
+    network: NetworkConfig;
+    contract: ContractConfig;
+    /** Default gas limit for write calls. */
+    defaultGasLimit?: number;
+    /** Default gas price (quar) for write calls. Ignis devnet base fee = 5000. */
+    defaultGasPrice?: string;
+}
+/** Resolve a contract export prefix, deriving the default from the name. */
+declare function exportPrefixFor(contract: ContractConfig): string;
+declare const DEFAULT_GAS_LIMIT = 200000;
+declare const DEFAULT_GAS_PRICE = "5000";
+/**
+ * A never-minted 32-byte sentinel capability id (witness v2, 32 bytes of 0xDE).
+ * Used as the counterparty placeholder when allowlist enforcement is disabled.
+ */
+declare const BURN_SENTINEL = "om1zmm0dahk7mm0dahk7mm0dahk7mm0dahk7mm0dahk7mm0dahk7mm0qdtuxap";
+/** Convenience preset for the local Ignis devnet. */
+declare const IGNIS_LOCAL: NetworkConfig;
+
+/**
+ * @cinchor/sdk — shared types and on-chain outcome codes.
+ *
+ * These mirror the typed return codes the on-chain accountability contract
+ * (the substrate Policy Enforcement Point) emits. They are the contract of the
+ * substrate, surfaced to the developer as named outcomes rather than integers.
+ */
+/** Lifecycle state of a capability (permission token). */
+declare enum CapabilityStatus {
+    NotFound = 0,
+    Active = 1,
+    Revoked = 2
+}
+type CapabilityStatusLabel = 'not_found' | 'active' | 'revoked';
+declare const CAPABILITY_STATUS_LABELS: readonly CapabilityStatusLabel[];
+/**
+ * Result of an `enforce()` call — the substrate's authorize-or-refuse verdict
+ * for an action recorded under a capability. Code 1 is the only allow; every
+ * other code is a substrate-enforced refusal (no state mutation occurred).
+ */
+declare enum EnforcementCode {
+    NotFound = 0,
+    Allowed = 1,
+    Revoked = 2,
+    Expired = 3,
+    OverBudget = 4,
+    OutOfAllowlist = 5
+}
+type EnforcementLabel = 'not_found' | 'allowed' | 'revoked' | 'expired' | 'over_budget' | 'out_of_allowlist';
+declare const ENFORCEMENT_LABELS: Record<EnforcementCode, EnforcementLabel>;
+/** Verdict committed alongside a decision attestation. */
+declare enum Verdict {
+    InPolicy = 1,
+    OutOfPolicy = 2
+}
+/** A signer compatible with the Omne SDK's WalletAccount.
+ *
+ * Defined structurally so callers can pass any object exposing an om1z
+ * `address` and a `signTransaction` method — they need not import the Omne
+ * SDK's concrete `WalletAccount` type to use Cinchor.
+ */
+interface Signer {
+    readonly address: string;
+    signTransaction(tx: Record<string, unknown>, opts?: {
+        chainId?: number;
+    }): {
+        from: string;
+        to: string;
+        value: string;
+        gasLimit: number;
+        gasPrice: string;
+        nonce: number;
+        chainId: number;
+        data?: string;
+        signature: string;
+        publicKey: string;
+    };
+}
+/** Receipt-shaped result returned from a committed (or pending) write. */
+interface SubmitReceipt {
+    transactionHash: string | null;
+    status: string;
+    blockNumber: number | null;
+    note?: string;
+}
+/** The outcome of an `enforce()` call. */
+interface EnforcementOutcome {
+    /** True only when the substrate authorized the action (code 1). */
+    allowed: boolean;
+    code: EnforcementCode;
+    reason: EnforcementLabel;
+    receipt: SubmitReceipt;
+}
+/** Full on-chain state of a capability. */
+interface CapabilityState {
+    capabilityId: string;
+    status: CapabilityStatus;
+    statusLabel: CapabilityStatusLabel;
+    principal: string;
+    agent: string;
+    maxSpend: bigint;
+    validUntil: bigint;
+    totalSpent: bigint;
+    actionCount: bigint;
+    createdAt: bigint;
+    revokedAt: bigint;
+}
+/** On-chain record of a decision attestation (the tamper-evidence anchor). */
+interface AttestationRecord {
+    exists: boolean;
+    contextHash: string;
+    policyVersion: bigint;
+    verdict: number;
+    time: bigint;
+}
+
+/**
+ * @cinchor/sdk — typed wrapper over the deployed accountability contract.
+ *
+ * Each method maps to a contract export, encoding arguments per the on-chain
+ * ABI and parsing the returned state. This is the low-level primitive layer;
+ * most consumers use the high-level {@link CinchorClient} facade instead.
+ *
+ * Read methods (query) work standalone — no wallet/signing required.
+ * Write methods (call) require a signer whose om1z address is funded to pay gas.
+ *
+ * Substrate-enforced invariants for an action (in precedence order):
+ *   0 = not_found, 1 = success, 2 = revoked, 3 = expired, 4 = over_budget,
+ *   5 = out_of_allowlist.
+ */
+
+declare class CapabilityRegistry {
+    private readonly contract;
+    private readonly rpcUrl;
+    private readonly chainId;
+    private readonly contractAddress;
+    private readonly exportPrefix;
+    private readonly defaultGasLimit;
+    private readonly defaultGasPrice;
+    /** Per-signer next-nonce cache (see {@link sendSigned} for node nonce semantics). */
+    private readonly nonces;
+    private constructor();
+    static connect(config: CinchorConfig): Promise<CapabilityRegistry>;
+    private fn;
+    /** A single, non-retrying JSON-RPC POST. */
+    private rpc;
+    /**
+     * Build, SIGN, and submit a state-changing contract call. The Omne node
+     * mandates a valid ML-DSA-44 signature on every transaction; we encode the
+     * call data, build the transaction, sign it with the role's signer (chainId
+     * 3 = Ignis), and submit via a single raw JSON-RPC POST. The submitter
+     * ("from") must equal the signer's om1z address — the node re-derives the PQC
+     * address from the public key and checks it matches.
+     */
+    private sendSigned;
+    /** Fetch the signer's next nonce from the node (0 on this devnet). */
+    private fetchNonce;
+    /**
+     * Build a signed wire payload for a contract call at a given nonce, validating
+     * the ML-DSA-44 signature/pubkey/chainId lengths locally before submit so a
+     * malformed signed object fails fast here, not at the node.
+     */
+    private buildSignedWire;
+    /** Submit a signed wire payload with one non-retrying POST. */
+    private submitOnce;
+    /**
+     * Poll for a transaction receipt, tolerating the node's "receipt not found"
+     * RPC error while the tx is still in the mempool. 60s default: a 4-node BFT
+     * mesh confirms contract calls in ~20-30s.
+     */
+    private pollReceipt;
+    private queryNumber;
+    private queryBigInt;
+    private queryAddress;
+    getStatus(capabilityId: string): Promise<number>;
+    getMaxSpend(capabilityId: string): Promise<bigint>;
+    getValidUntil(capabilityId: string): Promise<bigint>;
+    getTotalSpent(capabilityId: string): Promise<bigint>;
+    getActionCount(capabilityId: string): Promise<bigint>;
+    getCreatedAt(capabilityId: string): Promise<bigint>;
+    getRevokedAt(capabilityId: string): Promise<bigint>;
+    getPolicyVersion(capabilityId: string): Promise<bigint>;
+    getAttestationCount(capabilityId: string): Promise<bigint>;
+    getAllowlistEnabled(capabilityId: string): Promise<boolean>;
+    isCounterpartyAllowed(capabilityId: string, counterparty: string): Promise<boolean>;
+    /** Read a decision attestation's on-chain record (the tamper-evidence anchor). */
+    getAttestation(attestationId: string): Promise<AttestationRecord>;
+    /** Fetch the complete state of a capability in one call. */
+    getCapabilityState(capabilityId: string): Promise<CapabilityState>;
+    /** Principal mints a scoped capability to an agent. Signed by the principal. */
+    mintPermission(opts: {
+        signer: Signer;
+        capabilityId: string;
+        principal: string;
+        agent: string;
+        maxSpend: bigint;
+        validUntil: bigint;
+        allowlistEnabled?: boolean;
+        currentTime: bigint;
+        gasLimit?: number;
+    }): Promise<SubmitReceipt>;
+    /** Principal authorizes a counterparty for a capability's allowlist. */
+    addAllowedCounterparty(opts: {
+        signer: Signer;
+        capabilityId: string;
+        counterparty: string;
+        currentTime: bigint;
+        gasLimit?: number;
+    }): Promise<SubmitReceipt>;
+    /** Principal updates a capability's policy (limits) and bumps its on-chain version. */
+    updatePolicy(opts: {
+        signer: Signer;
+        capabilityId: string;
+        newMaxSpend: bigint;
+        newValidUntil: bigint;
+        currentTime: bigint;
+        gasLimit?: number;
+    }): Promise<SubmitReceipt>;
+    /**
+     * Agent records a capability-bound action — the substrate Policy Enforcement
+     * Point. Signed by the agent. `counterparty` is ignored when the capability's
+     * allowlist is disabled; when enabled, the substrate refuses (code 5) unless
+     * the counterparty has been allowlisted.
+     */
+    recordAction(opts: {
+        signer: Signer;
+        capabilityId: string;
+        amountSpent: bigint;
+        counterparty?: string;
+        currentTime: bigint;
+        gasLimit?: number;
+    }): Promise<SubmitReceipt>;
+    /** Principal revokes a capability. Terminal. Signed by the principal. */
+    revokePermission(opts: {
+        signer: Signer;
+        capabilityId: string;
+        currentTime: bigint;
+        gasLimit?: number;
+    }): Promise<SubmitReceipt>;
+    /**
+     * Agent records a decision attestation (provable-after). Commits the
+     * decision's context_hash + verdict, bound to the capability's current policy
+     * version. Signed by the agent.
+     */
+    recordAttestation(opts: {
+        signer: Signer;
+        attestationId: string;
+        capabilityId: string;
+        contextHash: string;
+        verdict: number;
+        currentTime: bigint;
+        gasLimit?: number;
+    }): Promise<SubmitReceipt>;
+}
+/**
+ * Parse an address return value from a contract query. The chain is uniformly
+ * 32-byte (PQC, witness v2); we normalize to 32 bytes and re-encode to om1z. A
+ * short hex value is zero-padded to 32 bytes (never 20) so a runtime returning
+ * the wrong width surfaces as a clearly-wrong address, not a silently-valid one.
+ */
+declare function parseAddressReturn(returnValue: ContractQueryResult['returnValue']): string;
+
+/**
+ * @cinchor/sdk — the high-level developer facade.
+ *
+ * Two verbs carry the product:
+ *   - enforce(action)  — authorize-or-refuse a consequential action. The
+ *                        substrate is the Policy Enforcement Point: an
+ *                        out-of-scope action commits no state change.
+ *   - attest(decision) — commit a tamper-evident, independently-verifiable
+ *                        record of a decision and its context.
+ *
+ * Plus the capability lifecycle (mint / revoke / update / allow-counterparty)
+ * and the audit reads a relying party uses to verify without trusting you.
+ *
+ * The chain is the substrate, not the product: callers `import` this, wrap
+ * their agent's decision points, and never manage a blockchain.
+ */
+
+/** Current UNIX time in seconds, as the bigint the contract expects. */
+declare function nowSecs(): bigint;
+interface MintCapabilityOptions {
+    /** The principal granting authority. Signs the mint. */
+    principal: Signer;
+    /** om1z address of the agent being granted scoped authority. */
+    agent: string;
+    /** Spend ceiling (in the unit the action amounts are denominated in). */
+    maxSpend: bigint;
+    /** Absolute expiry (UNIX seconds). Provide this OR `ttlSeconds`. */
+    validUntil?: bigint;
+    /** Relative expiry from now (seconds). Used when `validUntil` is omitted. */
+    ttlSeconds?: number;
+    /** Enforce a counterparty allowlist on every action under this capability. */
+    allowlist?: boolean;
+    /** Uniqueness nonce for the derived id. Defaults to a random value. */
+    nonce?: number;
+    /** Override the recorded creation time (UNIX seconds). Defaults to now. */
+    currentTime?: bigint;
+    gasLimit?: number;
+}
+interface MintCapabilityResult {
+    capabilityId: string;
+    receipt: SubmitReceipt;
+}
+interface EnforceOptions {
+    /** The capability id authorizing this action. */
+    capability: string;
+    /** The agent performing the action. Signs the record. */
+    agent: Signer;
+    /** Amount this action spends against the capability's ceiling. */
+    amount: bigint;
+    /** om1z counterparty the action transacts with (required if allowlisted). */
+    counterparty?: string;
+    /** Override the action time (UNIX seconds). Defaults to now. */
+    currentTime?: bigint;
+    gasLimit?: number;
+}
+interface AttestOptions {
+    /** The capability the decision was made under (binds the policy version). */
+    capability: string;
+    /** The agent attesting. Signs the attestation. */
+    agent: Signer;
+    /** The full decision context. Hashed canonically; the hash is committed. */
+    context: unknown;
+    /** Verdict committed alongside the context. Defaults to in-policy. */
+    verdict?: Verdict;
+    /** Sequence number disambiguating multiple attestations. Defaults to 0. */
+    seq?: number;
+    currentTime?: bigint;
+    gasLimit?: number;
+}
+interface AttestResult {
+    attestationId: string;
+    contextHash: string;
+    verdict: Verdict;
+    receipt: SubmitReceipt;
+}
+declare class CinchorClient {
+    readonly registry: CapabilityRegistry;
+    private constructor();
+    /** Connect to a network + deployed accountability contract. */
+    static connect(config: CinchorConfig): Promise<CinchorClient>;
+    /**
+     * Mint a cryptographically-scoped capability to an agent: capability, spend
+     * ceiling, validity window, revocable at will. Returns the derived capability
+     * id and the commit receipt.
+     */
+    mintCapability(opts: MintCapabilityOptions): Promise<MintCapabilityResult>;
+    /** Revoke a capability. Terminal. Signed by the principal. */
+    revoke(opts: {
+        capability: string;
+        principal: Signer;
+        currentTime?: bigint;
+        gasLimit?: number;
+    }): Promise<SubmitReceipt>;
+    /** Update a capability's policy (limits) and bump its on-chain version. */
+    updatePolicy(opts: {
+        capability: string;
+        principal: Signer;
+        maxSpend: bigint;
+        validUntil: bigint;
+        currentTime?: bigint;
+        gasLimit?: number;
+    }): Promise<SubmitReceipt>;
+    /** Authorize a counterparty for a capability's allowlist. */
+    allowCounterparty(opts: {
+        capability: string;
+        principal: Signer;
+        counterparty: string;
+        currentTime?: bigint;
+        gasLimit?: number;
+    }): Promise<SubmitReceipt>;
+    /**
+     * Authorize-or-refuse a consequential action. The substrate enforces the
+     * capability's invariants atomically: an out-of-scope action commits no state
+     * change. The verdict is read back from committed state (a record_action
+     * receipt does not carry the contract's return code).
+     *
+     * Verdict classification assumes serial, single-signer use of the capability
+     * (one in-flight action at a time) — the documented integration pattern.
+     */
+    enforce(opts: EnforceOptions): Promise<EnforcementOutcome>;
+    private classify;
+    /**
+     * Commit a tamper-evident attestation of a decision. The full context is
+     * hashed canonically; the hash + verdict are committed on-chain, bound to the
+     * capability's current policy version. An auditor later re-hashes the
+     * off-chain artifact and confirms it matches (see {@link verifyAttestation}).
+     */
+    attest(opts: AttestOptions): Promise<AttestResult>;
+    /** Read the full on-chain state of a capability. */
+    getCapability(capabilityId: string): Promise<CapabilityState>;
+    /** Read a decision attestation's on-chain record. */
+    getAttestation(attestationId: string): Promise<AttestationRecord>;
+    /**
+     * Tamper check: re-hash a decision context and confirm it matches the
+     * attestation's on-chain commitment. Returns whether it matches, the
+     * recomputed hash, and the on-chain record.
+     */
+    verifyAttestation(context: unknown, attestationId: string): Promise<{
+        ok: boolean;
+        recomputed: string;
+        onChain: AttestationRecord;
+    }>;
+}
+
+/**
+ * @cinchor/sdk — Omne address + identifier encoding.
+ *
+ * The Omne chain is uniformly 32-byte (post-quantum). On-chain addresses and
+ * contract map-key identifiers (capability ids, attestation ids) are bech32m
+ * encodings of a 32-byte payload under witness version 2. This module produces
+ * ABI arguments in that on-chain format and derives the deterministic ids the
+ * accountability contract keys its state by.
+ *
+ * Format: bech32m("om", [0x02, ...toWords(32-byte payload)])  →  62-char "om1z…"
+ */
+
+/** Decode an om1z bech32m address to its raw 32-byte payload. */
+declare function decodeAddress(address: string): Uint8Array;
+/** Encode a raw 32-byte payload as canonical om1z bech32m. Rejects non-32-byte input. */
+declare function encodeAddress(payload: Uint8Array): string;
+/**
+ * Build an ABI `Address` argument from an om1z string. Uses the 32-byte payload
+ * directly — the substrate runtime accepts the Address discriminant + 32-byte
+ * payload because that matches the on-chain representation.
+ */
+declare function addressArg(address: string): AbiArgument;
+/**
+ * Derive a deterministic capability id from (principal, agent, nonce, createdAt).
+ * Returns a 32-byte om1z address matching the chain's uniform width, so it
+ * round-trips through the contract's address-typed map key.
+ */
+declare function deriveCapabilityId(principal: string, agent: string, nonce: number, createdAt: number): Promise<string>;
+/**
+ * Derive the per-(capability, counterparty) allowlist key the contract stores
+ * and checks. The contract is agnostic to the derivation — it only compares
+ * stored keys — so the SDK owns it; minting an allowed counterparty and
+ * enforcing an action MUST use the same derivation. Capability-scoped (the id
+ * is in the preimage) so there is no cross-capability collision.
+ */
+declare function counterpartyKey(capabilityId: string, counterparty: string): Promise<string>;
+
+/**
+ * @cinchor/sdk — decision attestation (provable-after).
+ *
+ * A decision attestation commits, on-chain, the HASH of a decision's full
+ * context (inputs the agent saw, policy version, model, reasoning, output) plus
+ * a verdict — bound to the policy version in force at decision time. The full
+ * artifact lives off-chain; the tamper-evidence property is that anyone can
+ * re-hash the off-chain artifact and confirm it matches the on-chain
+ * context_hash. If a byte changed, the hashes diverge and tampering is detected.
+ *
+ * This is what makes non-payment decisions (claims denials, underwriting calls)
+ * accountable: provable after the fact to a party who does not trust the operator.
+ */
+/**
+ * Deterministic JSON: object keys sorted recursively so the same logical
+ * context always serializes to the same bytes (stable hashing across machines).
+ */
+declare function canonicalJson(value: unknown): string;
+/** Hash a decision-context object to a 32-byte om1z commitment. */
+declare function hashDecisionContext(context: unknown): Promise<string>;
+/**
+ * Derive a deterministic attestation id from (capabilityId, contextHash, seq).
+ * The contract enforces first-write, so reuse fails. Returns a 32-byte om1z id.
+ */
+declare function deriveAttestationId(capabilityId: string, contextHash: string, seq: number): Promise<string>;
+/**
+ * Tamper check: re-hash a decision context and confirm it matches the on-chain
+ * commitment. Returns whether it matches and the recomputed hash.
+ */
+declare function verifyDecisionContext(context: unknown, onChainContextHash: string): Promise<{
+    ok: boolean;
+    recomputed: string;
+}>;
+
+export { type AttestOptions, type AttestResult, type AttestationRecord, BURN_SENTINEL, CAPABILITY_STATUS_LABELS, CapabilityRegistry, type CapabilityState, CapabilityStatus, type CapabilityStatusLabel, CinchorClient, type CinchorConfig, type ContractConfig, DEFAULT_GAS_LIMIT, DEFAULT_GAS_PRICE, ENFORCEMENT_LABELS, type EnforceOptions, EnforcementCode, type EnforcementLabel, type EnforcementOutcome, IGNIS_LOCAL, type MintCapabilityOptions, type MintCapabilityResult, type NetworkConfig, type Signer, type SubmitReceipt, Verdict, addressArg, canonicalJson, counterpartyKey, decodeAddress, deriveAttestationId, deriveCapabilityId, encodeAddress, exportPrefixFor, hashDecisionContext, nowSecs, parseAddressReturn, verifyDecisionContext };