@onchaindiligence/sdk 0.2.0 → 0.3.0

package/dist/commerce/results.d.ts

@@ -0,0 +1,90 @@
+/**
+ * results.ts — discriminated unions for every lifecycle outcome (D2.5,
+ * Section 2). Ordinary lifecycle states are never thrown as exceptions —
+ * only genuinely exceptional conditions (bad input, a network the caller
+ * cannot reasonably plan around) do. `receipt-produced` deliberately does
+ * NOT mean "payment succeeded": the receipt may describe a confirmed
+ * payment, a failed execution, a mismatch, or an uncertain observation —
+ * read `receipt.receipt.execution.status` / `.settlement.status` /
+ * `.decision.status`, never infer success from a receipt merely existing.
+ */
+import type { ReceiptEnvelope, OperationStatus } from './types.js';
+/** Shared shape for every non-terminal "come back later" outcome. */
+export interface PendingInfo {
+    /** Where in the lifecycle this operation currently sits. */
+    phase: 'preflight-in-progress' | 'awaiting-execution' | 'execution-ambiguous' | 'awaiting-observation' | 'observation-pending';
+    /** What the caller should do next, in plain language a UI can show directly. */
+    safeNextAction: string;
+    /** Seconds to wait before retrying, when known. */
+    retryAfterSeconds?: number;
+    /** True whenever OCD's fee (or, for execution, the merchant payment) may already have been taken — the caller must NEVER treat this as "safe to pay again". */
+    mayAlreadyHavePaid: boolean;
+    operationId: string;
+    executionRequestId?: string | null;
+}
+export type PreflightEvaluation = {
+    kind: 'ready';
+    operationId: string;
+    receipt: ReceiptEnvelope;
+    capabilityExpiresAt: string;
+} | {
+    kind: 'blocked';
+    operationId: string;
+    receipt: ReceiptEnvelope;
+    reasons: string[];
+} | {
+    kind: 'approval-required';
+    operationId: string;
+    receipt: ReceiptEnvelope;
+    reasons: string[];
+} | ({
+    kind: 'pending';
+} & PendingInfo) | {
+    kind: 'terminal-error';
+    operationId: string;
+    error: string;
+};
+export type ExecutionRecord = {
+    kind: 'execution-recorded';
+    operationId: string;
+    executionRequestId: string;
+    transactionHash: string;
+    providerReference?: string | null;
+} | {
+    kind: 'manual-recovery-required';
+    operationId: string;
+    executionRequestId: string;
+    reason: string;
+} | ({
+    kind: 'pending';
+} & PendingInfo) | {
+    kind: 'terminal-error';
+    operationId: string;
+    error: string;
+};
+export type FinalizeResult = {
+    kind: 'receipt-produced';
+    operationId: string;
+    receipt: ReceiptEnvelope;
+    evidence: {
+        bundle_digest: string;
+        binding_strength: 'TRANSFER_MATCH_ONLY' | 'EXECUTOR_CORRELATED' | 'PAYMENT_IDENTITY_LINKED';
+    } | null;
+} | ({
+    kind: 'pending';
+} & PendingInfo) | {
+    kind: 'terminal-error';
+    operationId: string;
+    error: string;
+};
+export type ResumeResult = {
+    kind: 'resumed';
+    operationId: string;
+    status: OperationStatus;
+} | {
+    kind: 'recovery-failed';
+    reason: string;
+};
+export declare function pending(operationId: string, info: Omit<PendingInfo, 'operationId'>): {
+    kind: 'pending';
+} & PendingInfo;

package/dist/commerce/results.js

@@ -0,0 +1,3 @@
+export function pending(operationId, info) {
+    return { kind: 'pending', operationId, ...info };
+}

package/dist/commerce/types.d.ts

@@ -0,0 +1,147 @@
+/**
+ * types.ts — the commerce-lifecycle wire contract, ported by hand from
+ * onchaindiligence-mcp's src/preflight.ts / src/receipts.ts / src/lifecycleRoute.ts
+ * / src/lifecycleFinalizeRoute.ts (D2.1/D2.4).
+ *
+ * SOURCE OF TRUTH: the deployed mcp.onchaindiligence.com API. This file does
+ * not implement or re-verify anything — it exists so the commerce client has
+ * exact types for what it sends and receives, mirroring the same
+ * "ported minimal copy, kept in sync by hand" discipline
+ * onchaindiligence-mcp's own receipts.ts already documents for its
+ * relationship to the canonical packages/agent-evidence source.
+ */
+export interface CommerceAction {
+    kind: 'PAYMENT';
+    /** URL of the resource/service the payment is for, if any. */
+    resource: string | null;
+    /** CAIP-2 network identifier, e.g. "eip155:8453" for Base mainnet. */
+    network: string;
+    /** Canonical ERC-20 token contract address — never a bare ticker. */
+    asset: string;
+    /** Canonical decimal string, e.g. "1.00". Never a float. */
+    amount: string;
+    sender: string | null;
+    recipient: string;
+}
+export interface CommercePolicy {
+    max_amount?: string | null;
+    allowed_networks?: string[] | null;
+    allowed_assets?: string[] | null;
+    expected_recipient?: string | null;
+    allowed_resource_origins?: string[] | null;
+    /** Structural confirmation that every field above being null/omitted is intentional, not an accident. */
+    acknowledge_unconstrained?: boolean;
+    /** A frozen commitment to the wallet expected to AUTHORIZE the eventual on-chain payment (D2.4) — decision-neutral. */
+    expected_payer?: string | null;
+}
+export interface CommercePublication {
+    preflight?: boolean;
+    commerce?: boolean;
+}
+export type DecisionStatus = 'ALLOW' | 'REQUIRE_APPROVAL' | 'BLOCK' | 'UNKNOWN';
+export interface ReceiptDecision {
+    status: DecisionStatus;
+    authorized: boolean | null;
+    reasons: string[];
+}
+export interface ReceiptCheck {
+    id: string;
+    result: 'PASS' | 'FAIL' | 'UNKNOWN' | 'NOT_CHECKED';
+    summary: string;
+    evidence_digest: string | null;
+}
+export type ExecutionStatus = 'NOT_SUBMITTED' | 'SUBMITTED' | 'CONFIRMED' | 'FAILED' | 'UNKNOWN';
+export type SettlementStatus = 'CONFIRMED' | 'NOT_CONFIRMED' | 'UNVERIFIED' | 'NOT_APPLICABLE';
+export interface Receipt {
+    receipt_id: string;
+    receipt_digest: string;
+    receipt_type: 'ACTION' | 'PREFLIGHT' | 'COMMERCE';
+    issued_at: string;
+    action: CommerceAction & {
+        resource: string | null;
+    };
+    decision: ReceiptDecision;
+    execution: {
+        provider: string | null;
+        status: ExecutionStatus;
+        transaction_hash: string | null;
+        submitted_at: string | null;
+        confirmed_at: string | null;
+    };
+    settlement: {
+        status: SettlementStatus;
+        detail: string | null;
+    };
+    checks: ReceiptCheck[];
+    links: {
+        agent_evidence_bundle_digest: string | null;
+        preflight_receipt_id: string | null;
+    };
+    limitations: string[];
+}
+export interface ReceiptEnvelope {
+    schema: string;
+    receipt: Receipt;
+    proof: {
+        signed: boolean;
+        schema_version?: string;
+        issuer?: string;
+        purpose?: string;
+        issued_at?: string;
+        key_id?: string;
+        algorithm?: string;
+        canonicalization?: string;
+        signature?: string;
+        signing_input_hint?: string;
+    };
+}
+export interface PreflightFinalization {
+    capability: string;
+    expires_at: string;
+    endpoint: string;
+}
+export interface PreflightResponseBody {
+    decision: ReceiptDecision;
+    checks: ReceiptCheck[];
+    receipt: ReceiptEnvelope;
+    finalization: PreflightFinalization;
+}
+export interface CreatedOperation {
+    operation_id: string;
+    recovery_credential: string;
+}
+export type PreflightState = 'not_started' | 'in_progress' | 'completed';
+export type ExecutionState = 'not_submitted' | 'prepared' | 'submission_ambiguous' | 'submitted' | 'outcome_unknown' | 'transaction_known' | 'manual_recovery_required';
+export type ObservationState = 'none' | 'pending' | 'confirmed' | 'contradicted';
+export type ReceiptState = 'none' | 'preflight_only' | 'commerce_issued';
+export interface OperationStatus {
+    operation_id: string;
+    preflight_state: PreflightState;
+    execution_state: ExecutionState;
+    observation_state: ObservationState;
+    receipt_state: ReceiptState;
+    preflight_receipt_id: string | null;
+}
+export interface ExecutionBindingResponse {
+    execution_request_id: string;
+    submission_state: ExecutionState;
+    idempotent_replay: boolean;
+}
+export interface FinalizeExecutionInput {
+    transaction_hash: string;
+    execution_provider: 'x402' | 'paybox' | 'wallet' | 'other';
+    provider_reference?: string | null;
+    result_digest?: string | null;
+    execution_request_id?: string | null;
+}
+export interface OperationFinalizeResponseBody extends ReceiptEnvelope {
+    ocd_lifecycle_evidence: {
+        bundle_digest: string;
+        binding_strength: 'TRANSFER_MATCH_ONLY' | 'EXECUTOR_CORRELATED' | 'PAYMENT_IDENTITY_LINKED';
+    } | null;
+}
+/** The shape of an API error body across every endpoint used here. */
+export interface ApiErrorBody {
+    error: string;
+    reason?: string;
+}

package/dist/commerce/types.js

@@ -0,0 +1,13 @@
+/**
+ * types.ts — the commerce-lifecycle wire contract, ported by hand from
+ * onchaindiligence-mcp's src/preflight.ts / src/receipts.ts / src/lifecycleRoute.ts
+ * / src/lifecycleFinalizeRoute.ts (D2.1/D2.4).
+ *
+ * SOURCE OF TRUTH: the deployed mcp.onchaindiligence.com API. This file does
+ * not implement or re-verify anything — it exists so the commerce client has
+ * exact types for what it sends and receives, mirroring the same
+ * "ported minimal copy, kept in sync by hand" discipline
+ * onchaindiligence-mcp's own receipts.ts already documents for its
+ * relationship to the canonical packages/agent-evidence source.
+ */
+export {};

package/dist/commerce/x402Executor.d.ts

@@ -0,0 +1,43 @@
+import { toClientEvmSigner, type ClientEvmSigner } from '@x402/evm';
+import type { CommerceExecutor, PrepareContext, PrepareResult, ExecutionResult, ExecutorRecoveryMode } from './executor.js';
+export type { ClientEvmSigner };
+export { toClientEvmSigner };
+export declare const BASE_NETWORK = "eip155:8453";
+export declare const BASE_USDC = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+/** The subset of viem's PublicClient resume() actually calls -- narrowed so tests can inject a minimal fake instead of a real RPC connection. */
+export interface MinimalResumeClient {
+    getTransactionReceipt: (args: {
+        hash: `0x${string}`;
+    }) => Promise<unknown>;
+}
+export interface X402ExecutorOptions {
+    /**
+     * Signs the EIP-3009 payment authorization. Never logged, never persisted
+     * by this class. `@x402/evm`'s own ExactEvmScheme wants exactly this
+     * shape (address + signTypedData), NOT a full viem Account/WalletClient --
+     * that's deliberate: it's the one interface both a Node private-key
+     * signer (`toClientEvmSigner(privateKeyToAccount(pk))`, re-exported from
+     * this module) and a browser injected-wallet signer (hand-built around
+     * `walletClient.signTypedData`, since an injected wallet's viem account has
+     * no signing methods of its own) can equally satisfy.
+     */
+    signer: ClientEvmSigner;
+    /** Base RPC used ONLY for read-only resume confirmation. Defaults to the public Base RPC. */
+    rpcUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    /** Test seam: inject a fake read-only client instead of connecting to rpcUrl. */
+    publicClient?: MinimalResumeClient;
+}
+export declare class X402BaseUsdcExecutor implements CommerceExecutor {
+    readonly id = "x402-base-usdc-exact";
+    readonly version = "v1";
+    readonly recoveryMode: ExecutorRecoveryMode;
+    private readonly signer;
+    private readonly fetchImpl;
+    private readonly rpcUrl;
+    private readonly injectedPublicClient?;
+    constructor(options: X402ExecutorOptions);
+    prepare(context: PrepareContext): Promise<PrepareResult>;
+    submit(prepared: PrepareResult): Promise<ExecutionResult>;
+    resume(prepared: PrepareResult, priorOutcome?: ExecutionResult): Promise<ExecutionResult>;
+}

package/dist/commerce/x402Executor.js

@@ -0,0 +1,222 @@
+/**
+ * x402Executor.ts — the one narrow, production-quality executor adapter for
+ * the existing Base USDC x402 v2 "exact" flow (D2.5, Section 4).
+ *
+ * SCOPE, DELIBERATE: Base mainnet, USDC, x402 v2 exact scheme only — no
+ * other chain/asset/scheme. Reuses the EXACT same proven pattern as
+ * onchaindiligence-mcp's scripts/first-commerce-lifecycle.ts (D2.2A) and
+ * operator/src/main.ts (D2.2B), the only two places this integration has
+ * ever moved real money: `wrapFetchWithPayment` + `x402Client` +
+ * `ExactEvmScheme(signer)`, called through EXACTLY ONCE per submit().
+ *
+ * RECOVERY MODE IS HONESTLY 'manual', not 'stable-payment-identity':
+ * `wrapFetchWithPayment` is an atomic sign-and-pay primitive — it does not
+ * expose the ERC-3009 nonce it generates internally, so if `submit()` never
+ * receives a response (timeout, connection drop), this adapter has no
+ * independent identity to query "was this specific authorization consumed"
+ * against. A deeper integration COULD extract the nonce via
+ * `ExactEvmScheme.createPaymentPayload()` and later check it on-chain via
+ * USDC's own `authorizationState(authorizer, nonce)` view function — but
+ * that path is unproven against the real facilitator (verifying it would
+ * require a live payment, which no milestone through D2.5 permits) and is
+ * therefore NOT implemented here. Reporting 'manual' honestly, and resolving
+ * to manual-recovery-required on an ambiguous submit, is the correct choice
+ * over pretending a recovery guarantee this code cannot actually back up —
+ * see onchaindiligence-mcp's own D2.4 executionBinding.ts: "It is preferable
+ * to pretending exactly-once execution can be guaranteed."
+ *
+ * The ONE exception: if `submit()` DID receive a response before some LATER
+ * step failed (so a transaction hash is already known), `resume()` can and
+ * does independently re-confirm it read-only on-chain — no guessing, no new
+ * payment, just checking what's already claimed.
+ */
+import { createPublicClient, http } from 'viem';
+import { base } from 'viem/chains';
+import { wrapFetchWithPayment } from '@x402/fetch';
+import { x402Client } from '@x402/core/client';
+import { ExactEvmScheme } from '@x402/evm/exact/client';
+import { toClientEvmSigner } from '@x402/evm';
+export { toClientEvmSigner };
+export const BASE_NETWORK = 'eip155:8453';
+export const BASE_USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+/**
+ * `Buffer` is a Node global, not a browser one -- calling `Buffer.from(...)`
+ * here used to throw `ReferenceError: Buffer is not defined` in a real
+ * browser (confirmed live, D2.5A: a real OneSource 402 challenge, valid and
+ * byte-identical through the local proxy, failed to decode). That
+ * ReferenceError was thrown INSIDE decodeChallenge()'s try/catch below and
+ * silently relabeled as "Payment-Required header was not base64-encoded
+ * JSON" -- a misleading error that looks like a merchant-format problem but
+ * isn't one. `atob`/`TextDecoder` are the browser-safe equivalents (both
+ * also globally available in Node), mirroring lifecycleCore.ts's own
+ * isomorphic decodeChallenge in onchaindiligence-mcp exactly.
+ */
+function base64ToUtf8(base64) {
+    const binary = atob(base64);
+    const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+}
+class X402ChallengeError extends Error {
+}
+function decodeChallenge(res) {
+    const header = res.headers.get('payment-required');
+    if (!header)
+        throw new X402ChallengeError(`${res.url}: 402 response carried no Payment-Required header`);
+    try {
+        return JSON.parse(base64ToUtf8(header));
+    }
+    catch {
+        throw new X402ChallengeError(`${res.url}: Payment-Required header was not base64-encoded JSON`);
+    }
+}
+/** Validates a decoded x402 v2 "exact" challenge against the frozen preflighted action. Never mutates anything; throws before any signing could occur. */
+function validateChallenge(challenge, expected) {
+    if (challenge?.x402Version !== 2)
+        throw new X402ChallengeError(`unexpected x402 version ${challenge?.x402Version} (expected 2)`);
+    const accepts = challenge?.accepts?.[0];
+    if (!accepts)
+        throw new X402ChallengeError('challenge contained no accepts entry');
+    if (accepts.scheme !== 'exact')
+        throw new X402ChallengeError(`unexpected scheme "${accepts.scheme}" (expected "exact")`);
+    if (accepts.network !== expected.network)
+        throw new X402ChallengeError(`network mismatch: quoted "${accepts.network}", expected "${expected.network}"`);
+    if (String(accepts.asset).toLowerCase() !== expected.asset.toLowerCase()) {
+        throw new X402ChallengeError(`asset mismatch: quoted "${accepts.asset}", expected "${expected.asset}"`);
+    }
+    if (String(accepts.payTo).toLowerCase() !== expected.recipient.toLowerCase()) {
+        throw new X402ChallengeError(`recipient mismatch: quoted "${accepts.payTo}", expected "${expected.recipient}" -- refusing to pay an unexpected address`);
+    }
+    if (String(accepts.amount) !== expected.amount) {
+        throw new X402ChallengeError(`amount mismatch: quoted "${accepts.amount}", expected exactly "${expected.amount}" atomic units`);
+    }
+}
+function decodeSettlementResponse(res) {
+    const header = res.headers.get('x-payment-response') ?? res.headers.get('payment-response');
+    if (!header)
+        return { transactionHash: null };
+    try {
+        const decoded = JSON.parse(base64ToUtf8(header));
+        return { transactionHash: typeof decoded?.transaction === 'string' ? decoded.transaction : null };
+    }
+    catch {
+        return { transactionHash: null };
+    }
+}
+/**
+ * Converts a canonical decimal amount (e.g. "1.00") into USDC's 6-decimal
+ * atomic unit string, WITHOUT floating point — mirrors
+ * onchaindiligence-mcp's src/money.ts exactly (kept independent here since
+ * this package does not depend on that server-side module).
+ */
+function decimalToAtomic6(amount) {
+    const [intPart, fracPart = ''] = amount.split('.');
+    if (fracPart.length > 6)
+        throw new X402ChallengeError(`amount "${amount}" has more precision than USDC's 6 decimals support`);
+    return BigInt(intPart + fracPart.padEnd(6, '0')).toString();
+}
+export class X402BaseUsdcExecutor {
+    id = 'x402-base-usdc-exact';
+    version = 'v1';
+    recoveryMode = 'manual';
+    signer;
+    fetchImpl;
+    rpcUrl;
+    injectedPublicClient;
+    constructor(options) {
+        this.signer = options.signer;
+        // See client.ts's constructor comment: a bare `globalThis.fetch`
+        // reference, later invoked as `this.fetchImpl(...)`, throws "Illegal
+        // invocation" in real browsers (detached from its required receiver) --
+        // invisible under Node, which is why this only surfaces against a real
+        // injected-wallet browser flow. Bind it here so this executor is safe to
+        // construct with no `fetch` option in either environment.
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.rpcUrl = options.rpcUrl ?? 'https://mainnet.base.org';
+        this.injectedPublicClient = options.publicClient;
+    }
+    async prepare(context) {
+        if (context.action.network !== BASE_NETWORK)
+            throw new X402ChallengeError(`this executor only supports ${BASE_NETWORK}, got "${context.action.network}"`);
+        if (context.action.asset.toLowerCase() !== BASE_USDC.toLowerCase())
+            throw new X402ChallengeError(`this executor only supports USDC (${BASE_USDC}), got "${context.action.asset}"`);
+        if (!context.action.resource)
+            throw new X402ChallengeError('action.resource (the x402 resource URL) is required to prepare a submission');
+        // Provoke the 402 challenge with a plain, unauthenticated request --
+        // read-only, no signing, no payment. This is the ENTIRE point of
+        // prepare(): validate what we'd be agreeing to pay BEFORE any
+        // authorization exists.
+        const probe = await this.fetchImpl(context.action.resource);
+        if (probe.status !== 402) {
+            throw new X402ChallengeError(`expected HTTP 402 from ${context.action.resource}, got ${probe.status}`);
+        }
+        const challenge = decodeChallenge(probe);
+        const atomicAmount = decimalToAtomic6(context.action.amount);
+        validateChallenge(challenge, { network: context.action.network, asset: context.action.asset, amount: atomicAmount, recipient: context.action.recipient });
+        const reference = {
+            resourceUrl: context.action.resource,
+            network: context.action.network,
+            asset: context.action.asset,
+            atomicAmount,
+            recipient: context.action.recipient,
+        };
+        return { clientSubmissionKey: context.clientSubmissionKey, reference, preparedAt: new Date().toISOString() };
+    }
+    async submit(prepared) {
+        const ref = prepared.reference;
+        const client = new x402Client().register(ref.network, new ExactEvmScheme(this.signer));
+        const payingFetch = wrapFetchWithPayment(this.fetchImpl, client);
+        let res;
+        try {
+            res = await payingFetch(ref.resourceUrl);
+        }
+        catch (err) {
+            // No response at all -- the single most dangerous case: we genuinely
+            // do not know whether the facilitator ever broadcast the
+            // authorization. Never retry automatically; report ambiguous.
+            return { clientSubmissionKey: prepared.clientSubmissionKey, status: 'submission-ambiguous', reason: err?.message || 'no response from resource/facilitator' };
+        }
+        if (res.status === 402) {
+            // The payment was rejected outright (e.g. facilitator declined the
+            // authorization before ever broadcasting) -- this is a DEFINITIVE
+            // non-payment, safe to report as ambiguous-for-manual-review rather
+            // than a silent failure, since we still can't be 100% sure nothing
+            // was ever submitted on-chain by a misbehaving facilitator.
+            return { clientSubmissionKey: prepared.clientSubmissionKey, status: 'submission-ambiguous', reason: `resource still returned 402 after payment attempt (status ${res.status})` };
+        }
+        if (!res.ok) {
+            return { clientSubmissionKey: prepared.clientSubmissionKey, status: 'submission-ambiguous', reason: `resource returned HTTP ${res.status} after a payment attempt was made -- outcome unknown` };
+        }
+        const { transactionHash } = decodeSettlementResponse(res);
+        if (!transactionHash) {
+            // Paid successfully per the resource's own 2xx, but we couldn't parse
+            // a transaction hash out of the settlement response -- still
+            // ambiguous from OCD's perspective (D2.4 finalize needs the hash).
+            return { clientSubmissionKey: prepared.clientSubmissionKey, status: 'submission-ambiguous', reason: 'resource responded successfully but no transaction hash could be parsed from the settlement response' };
+        }
+        return { clientSubmissionKey: prepared.clientSubmissionKey, status: 'transaction-known', transactionHash, providerReference: this.id };
+    }
+    async resume(prepared, priorOutcome) {
+        // The only safe resume this adapter can do: if a transaction hash is
+        // ALREADY known (from a prior submit() that got a response before some
+        // later step failed), independently re-confirm it exists on-chain --
+        // never guess a new one, never resubmit.
+        if (priorOutcome?.status === 'transaction-known') {
+            const client = this.injectedPublicClient ?? createPublicClient({ chain: base, transport: http(this.rpcUrl) });
+            try {
+                await client.getTransactionReceipt({ hash: priorOutcome.transactionHash });
+                return priorOutcome;
+            }
+            catch {
+                // Not found (yet, or ever) -- still don't fabricate a different
+                // outcome; report ambiguous so the caller keeps trying, mirroring
+                // observeTransaction's own "not-found is not the same as failed".
+                return { clientSubmissionKey: prepared.clientSubmissionKey, status: 'submission-ambiguous', reason: 'previously reported transaction hash was not found on Base mainnet (may still be propagating)' };
+            }
+        }
+        return {
+            clientSubmissionKey: prepared.clientSubmissionKey,
+            status: 'manual-recovery-required',
+            reason: 'this executor cannot independently identify a submitted-but-unconfirmed x402 payment authorization -- check the merchant/your wallet history manually before retrying',
+        };
+    }
+}

package/dist/index.d.ts

@@ -22,31 +22,29 @@
  * build a payment header, or retry a request by hand.
  */
 import type { Account } from 'viem';
+import { type AttestationKeyRecord, type AttestationVerificationResult, type Signed, type VerifyAttestationOptions } from './verification.js';
+export * from './verification.js';
 export interface OnchainDiligenceOptions {
     /** A viem account used to sign/settle payments (e.g. privateKeyToAccount). */
     account: Account;
     /** Base URL of the API. Defaults to production. */
     baseUrl?: string;
+    /** Expected issuer for versioned attestations. Defaults to the production issuer. */
+    expectedAttestationIssuer?: string;
 }
-/** The signed-attestation envelope every paid response carries. */
-export interface Attestation {
-    signed: boolean;
-    key_id?: string;
-    algorithm?: string;
-    signature?: string;
-    issued_at?: string;
-}
-export interface Signed<T> {
-    data: T;
-    attestation: Attestation;
-}
-/** Result of locally verifying a signed attestation. */
-export interface VerifyResult {
-    valid: boolean;
-    /** The key_id the signature was checked against, when available. */
-    keyId?: string;
-    /** Human-readable reason when `valid` is false. */
-    reason?: string;
+/** @deprecated Use AttestationVerificationResult and inspect its state. */
+export type VerifyResult = AttestationVerificationResult;
+export interface OnlineAttestationVerificationOptions extends VerifyAttestationOptions {
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Explicit policy decision to trust exact key records delivered by the
+     * configured HTTPS issuer registry. Without this, valid bytes remain
+     * UNVERIFIABLE for publisher identity.
+     */
+    trustRegistry?: boolean | ((record: AttestationKeyRecord, context: {
+        baseUrl: string;
+    }) => boolean | Promise<boolean>);
 }
 /** One address's outcome within a re-screen batch. */
 export interface RescreenItem {
@@ -168,10 +166,18 @@ export declare class OnchainDiligenceError extends Error {
     status: number;
     constructor(status: number, message: string);
 }
+export declare function resolveAttestationKeyOnline(keyId: string, options?: {
+    baseUrl?: string;
+    fetch?: typeof globalThis.fetch;
+}): Promise<AttestationKeyRecord>;
+/** Validate and return the complete signed envelope required by `/anchor`. */
+export declare function buildAnchorRequest(envelope: Signed<unknown>): Signed<unknown>;
+/** Explicit online-discovery wrapper around the zero-network verifier core. */
+export declare function verifyAttestationOnline(signed: unknown, options?: OnlineAttestationVerificationOptions): Promise<AttestationVerificationResult>;
 export declare class OnchainDiligence {
     private readonly baseUrl;
+    private readonly expectedAttestationIssuer;
     private readonly fetch;
-    private attestationKeyPem;
     constructor(opts: OnchainDiligenceOptions);
     private get;
     private post;
@@ -207,8 +213,8 @@ export declare class OnchainDiligence {
      * bad address never sinks the whole batch.
      */
     rescreen(addresses: string[], opts?: RescreenOptions): Promise<RescreenReport>;
-    /** Anchor an attestation's signature hash on Tempo (paid). */
-    anchor(signature: string): Promise<Signed<AnchorResult>>;
+    /** Anchor a complete authentic attestation envelope on Tempo (paid). */
+    anchor(envelope: Signed<unknown>): Promise<Signed<AnchorResult>>;
     /** Check whether an attestation has been anchored on-chain (free). */
     anchored(signature: string): Promise<AnchorStatus>;
     /** Service health (free). */
@@ -219,20 +225,18 @@ export declare class OnchainDiligence {
     }>;
     /**
      * Verify a signed attestation locally. Fetches the server's published
-     * Ed25519 public key once (cached), then checks the signature over the
-     * canonical signing input `JSON.stringify({ data, issued_at, key_id })` —
-     * the exact bytes the server signs. A `valid: true` result means the data
-     * has not been altered since the server signed it, provable without trusting
-     * this SDK.
+     * exact Ed25519 key identified by `key_id` (cached), then verifies either
+     * the domain-separated RFC 8785 version 2 input or the legacy version 1
+     * JSON.stringify input. Revoked/compromised keys remain cryptographically
+     * checkable but return `valid: false` and `trusted: false`.
      *
      * Uses WebCrypto (`globalThis.crypto.subtle`) so it runs dependency-free in
      * Node 18+, edge runtimes, and modern browsers.
      */
-    verifyAttestation(signed: Signed<unknown>): Promise<VerifyResult>;
     /**
-     * Fetch and cache the server's Ed25519 public key (PEM) from
-     * `/.well-known/attestation-key`. Accepts a raw PEM body or a JSON wrapper
-     * exposing the PEM under a common field name.
+     * Compatibility online wrapper. Prefer the standalone zero-network
+     * verifyAttestationOffline() with caller-supplied trust material.
      */
-    private getAttestationKeyPem;
+    verifyAttestation(signed: Signed<unknown>): Promise<VerifyResult>;
+    verifyAttestationOnline(signed: Signed<unknown>, options?: Omit<OnlineAttestationVerificationOptions, 'baseUrl' | 'fetch'>): Promise<AttestationVerificationResult>;
 }