@runtab/mcp 0.0.1

package/dist/paid-fetch-server.d.ts

@@ -0,0 +1,49 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { PaymentProfile } from "./payment-profile.js";
+import { type PaymentTargetLookup } from "./payment-target-network.js";
+import type { TabRemoteSigner } from "./remote-signer.js";
+interface PaidFetchServerOptions {
+    address: `0x${string}` | null;
+    allowDevelopmentLoopback?: boolean;
+    apiBaseUrl: string;
+    apiKey: string;
+    fetch?: typeof globalThis.fetch;
+    lookup?: PaymentTargetLookup;
+    paymentProfile: PaymentProfile;
+    signer?: TabRemoteSigner;
+}
+export declare function createPaidFetchServer(options: PaidFetchServerOptions): Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+}>;
+export {};

package/dist/paid-fetch-server.js

@@ -0,0 +1,104 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { PAID_FETCH_INPUT_SCHEMA, parsePaidFetchRequest, readBoundedResponse, readResponseHeaders, } from "./fetch-wire.js";
+import { createTabFetch } from "./fetch-wrapper.js";
+import { withPaymentIdempotencyKey } from "./payment-idempotency.js";
+import { withPaymentSignal } from "./payment-signal.js";
+import { createPinnedPaymentFetch } from "./payment-target-network.js";
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toolResponse(value, isError = false) {
+    return {
+        content: [{ text: JSON.stringify(value), type: "text" }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+function invalidRequest() {
+    return toolResponse({ error: { code: "INVALID_FETCH_REQUEST", message: "The fetch request is invalid." } }, true);
+}
+export function createPaidFetchServer(options) {
+    const server = new Server({ name: "tab-mcp", version: "0.0.1" }, { capabilities: { tools: {} } });
+    const allowDevelopmentLoopback = options.allowDevelopmentLoopback === true;
+    const baseFetch = options.fetch ?? globalThis.fetch;
+    const standalonePolicy = options.address
+        ? undefined
+        : createPinnedPaymentFetch({
+            allowDevelopmentLoopback,
+            fetch: baseFetch,
+            ...(options.lookup ? { lookup: options.lookup } : {}),
+        });
+    const leashFetch = options.address
+        ? createTabFetch({
+            address: options.address,
+            allowDevelopmentLoopback,
+            apiBaseUrl: options.apiBaseUrl,
+            apiKey: options.apiKey,
+            clientName: () => server.getClientVersion()?.name ?? "Unknown client",
+            fetch: baseFetch,
+            ...(options.lookup ? { lookup: options.lookup } : {}),
+            paymentProfile: options.paymentProfile,
+            ...(options.signer ? { signer: options.signer } : {}),
+        })
+        : undefined;
+    const fetch_ = leashFetch ?? standalonePolicy?.fetch;
+    if (!fetch_)
+        throw new Error("The paid fetch target policy is unavailable");
+    server.onclose = () => {
+        void (leashFetch?.close() ?? standalonePolicy?.close());
+    };
+    server.setRequestHandler(ListToolsRequestSchema, () => ({
+        tools: [
+            {
+                description: "Fetch an HTTP resource and pay a supported x402 challenge within owner policy.",
+                inputSchema: PAID_FETCH_INPUT_SCHEMA,
+                name: "paid_fetch",
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+        if (request.params.name !== "paid_fetch")
+            return invalidRequest();
+        let input;
+        try {
+            input = parsePaidFetchRequest(request.params.arguments, {
+                allowDevelopmentLoopback,
+            });
+        }
+        catch {
+            return invalidRequest();
+        }
+        try {
+            const signal = AbortSignal.any([extra.signal, AbortSignal.timeout(30_000)]);
+            const response = await withPaymentSignal(signal, () => withPaymentIdempotencyKey(input.idempotencyKey, () => fetch_(input.url, {
+                ...(input.body === undefined ? {} : { body: input.body }),
+                ...(input.headers === undefined ? {} : { headers: input.headers }),
+                method: input.method,
+                signal,
+            })));
+            if (!options.address && response.status === 402) {
+                void response.body?.cancel().catch(() => undefined);
+                return toolResponse({
+                    error: {
+                        code: "SIGNER_NOT_CONFIGURED",
+                        message: "Agent signing is not configured for this agent.",
+                    },
+                }, true);
+            }
+            const content = await readBoundedResponse(response);
+            return toolResponse({
+                ...content,
+                headers: readResponseHeaders(response),
+                status: response.status,
+                statusText: response.statusText,
+                url: response.url,
+            });
+        }
+        catch (error) {
+            const remoteCode = record(error) && typeof error.code === "string" ? error.code : "";
+            const code = /^[A-Z0-9_]{1,64}$/.test(remoteCode) ? remoteCode : "FETCH_FAILED";
+            return toolResponse({ error: { code, message: "The fetch request failed." } }, true);
+        }
+    });
+    return server;
+}

package/dist/payment-authorization-state.d.ts

@@ -0,0 +1,48 @@
+export declare const AUTHORIZATION_STATE_ABI: readonly [{
+    readonly inputs: readonly [{
+        readonly name: "authorizer";
+        readonly type: "address";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }];
+    readonly name: "authorizationState";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "view";
+    readonly type: "function";
+}];
+declare const NETWORKS: {
+    readonly "eip155:42161": {
+        readonly chainId: 42161;
+        readonly rpcUrl: "https://arb1.arbitrum.io/rpc";
+    };
+    readonly "eip155:8453": {
+        readonly chainId: 8453;
+        readonly rpcUrl: "https://mainnet.base.org";
+    };
+    readonly "eip155:84532": {
+        readonly chainId: 84532;
+        readonly rpcUrl: "https://sepolia.base.org";
+    };
+};
+interface PaymentAuthorizationIdentity {
+    asset: `0x${string}`;
+    from: `0x${string}`;
+    network: keyof typeof NETWORKS;
+    nonce: `0x${string}`;
+    validBefore: number;
+}
+interface AuthorizationStateOptions {
+    fetch?: typeof globalThis.fetch;
+    rpcUrl?: string;
+    signal?: AbortSignal;
+}
+export declare class PaymentReconciliationUnavailableError extends Error {
+    readonly code = "PAYMENT_RECONCILIATION_UNAVAILABLE";
+    constructor();
+}
+export declare function readPaymentAuthorizationState(identity: PaymentAuthorizationIdentity, options?: AuthorizationStateOptions): Promise<"unused" | "used">;
+export {};

package/dist/payment-authorization-state.js

@@ -0,0 +1,150 @@
+import { decodeFunctionResult, encodeFunctionData } from "viem";
+import { validatePaymentTarget } from "./payment-target-policy.js";
+import { ARBITRUM_NETWORK, BASE_NETWORK, BASE_SEPOLIA_NETWORK } from "./routing.js";
+export const AUTHORIZATION_STATE_ABI = [
+    {
+        inputs: [
+            { name: "authorizer", type: "address" },
+            { name: "nonce", type: "bytes32" },
+        ],
+        name: "authorizationState",
+        outputs: [{ name: "", type: "bool" }],
+        stateMutability: "view",
+        type: "function",
+    },
+];
+const NETWORKS = {
+    [ARBITRUM_NETWORK]: { chainId: 42_161, rpcUrl: "https://arb1.arbitrum.io/rpc" },
+    [BASE_NETWORK]: { chainId: 8_453, rpcUrl: "https://mainnet.base.org" },
+    [BASE_SEPOLIA_NETWORK]: { chainId: 84_532, rpcUrl: "https://sepolia.base.org" },
+};
+const MAX_RPC_RESPONSE_BYTES = 65_536;
+export class PaymentReconciliationUnavailableError extends Error {
+    code = "PAYMENT_RECONCILIATION_UNAVAILABLE";
+    constructor() {
+        super("Independent payment authorization state is unavailable.");
+        this.name = "PaymentReconciliationUnavailableError";
+    }
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function boundedJson(response, signal) {
+    if (!response.ok || !response.body)
+        throw new PaymentReconciliationUnavailableError();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    let rejectAbort;
+    const aborted = new Promise((_resolve, reject) => {
+        rejectAbort = reject;
+    });
+    const onAbort = () => {
+        void reader.cancel().catch(() => undefined);
+        rejectAbort?.(signal.reason);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    try {
+        if (signal.aborted)
+            onAbort();
+        while (true) {
+            const read = await Promise.race([reader.read(), aborted]);
+            if (read.done)
+                break;
+            length += read.value.byteLength;
+            if (length > MAX_RPC_RESPONSE_BYTES) {
+                await reader.cancel().catch(() => undefined);
+                throw new PaymentReconciliationUnavailableError();
+            }
+            chunks.push(read.value);
+        }
+    }
+    finally {
+        signal.removeEventListener("abort", onAbort);
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+}
+export async function readPaymentAuthorizationState(identity, options = {}) {
+    try {
+        const network = NETWORKS[identity.network];
+        if (!network)
+            throw new PaymentReconciliationUnavailableError();
+        const rpcUrl = validatePaymentTarget(options.rpcUrl ?? network.rpcUrl);
+        const timeout = AbortSignal.timeout(10_000);
+        const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+        const fetch_ = options.fetch ?? globalThis.fetch;
+        const request = async (body) => boundedJson(await fetch_(rpcUrl, {
+            body: JSON.stringify(body),
+            headers: { accept: "application/json", "content-type": "application/json" },
+            method: "POST",
+            redirect: "error",
+            signal,
+        }), signal);
+        const head = await request([
+            { id: 1, jsonrpc: "2.0", method: "eth_chainId", params: [] },
+            {
+                id: 2,
+                jsonrpc: "2.0",
+                method: "eth_getBlockByNumber",
+                params: ["finalized", false],
+            },
+        ]);
+        if (!Array.isArray(head))
+            throw new PaymentReconciliationUnavailableError();
+        const chain = head.find((entry) => record(entry) && entry.id === 1);
+        const block = head.find((entry) => record(entry) && entry.id === 2);
+        const finalized = record(block) && record(block.result) ? block.result : undefined;
+        if (!record(chain) ||
+            chain.result !== `0x${network.chainId.toString(16)}` ||
+            !finalized ||
+            typeof finalized.hash !== "string" ||
+            !/^0x[0-9a-fA-F]{64}$/.test(finalized.hash) ||
+            typeof finalized.number !== "string" ||
+            !/^0x[0-9a-fA-F]+$/.test(finalized.number) ||
+            typeof finalized.timestamp !== "string" ||
+            !/^0x[0-9a-fA-F]+$/.test(finalized.timestamp) ||
+            BigInt(finalized.timestamp) < BigInt(identity.validBefore)) {
+            throw new PaymentReconciliationUnavailableError();
+        }
+        const state = await request({
+            id: 3,
+            jsonrpc: "2.0",
+            method: "eth_call",
+            params: [
+                {
+                    data: encodeFunctionData({
+                        abi: AUTHORIZATION_STATE_ABI,
+                        args: [identity.from, identity.nonce],
+                        functionName: "authorizationState",
+                    }),
+                    to: identity.asset,
+                },
+                { blockHash: finalized.hash, requireCanonical: true },
+            ],
+        });
+        if (!record(state) ||
+            state.id !== 3 ||
+            typeof state.result !== "string" ||
+            !/^0x[0-9a-fA-F]+$/.test(state.result)) {
+            throw new PaymentReconciliationUnavailableError();
+        }
+        const used = decodeFunctionResult({
+            abi: AUTHORIZATION_STATE_ABI,
+            data: state.result,
+            functionName: "authorizationState",
+        });
+        return used ? "used" : "unused";
+    }
+    catch (error) {
+        if (error instanceof PaymentReconciliationUnavailableError)
+            throw error;
+        throw new PaymentReconciliationUnavailableError();
+    }
+}

package/dist/payment-client.d.ts

@@ -0,0 +1,4 @@
+import { x402Client } from "@x402/core/client";
+import type { PaymentProfile } from "./payment-profile.js";
+import type { TabRemoteSigner } from "./remote-signer.js";
+export declare function createLeashPaymentClient(signer: TabRemoteSigner, paymentProfile: PaymentProfile): x402Client;

package/dist/payment-client.js

@@ -0,0 +1,14 @@
+import { x402Client } from "@x402/core/client";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { ARBITRUM_NETWORK, BASE_NETWORK, BASE_SEPOLIA_NETWORK, selectLeashPaymentRequirements, } from "./routing.js";
+export function createLeashPaymentClient(signer, paymentProfile) {
+    const scheme = new ExactEvmScheme(signer);
+    const client = new x402Client((version, requirements) => selectLeashPaymentRequirements(paymentProfile, version, requirements));
+    if (paymentProfile === "base_sepolia_integration") {
+        client.register(BASE_SEPOLIA_NETWORK, scheme);
+    }
+    else {
+        client.register(BASE_NETWORK, scheme).register(ARBITRUM_NETWORK, scheme);
+    }
+    return client;
+}

package/dist/payment-correlation.d.ts

@@ -0,0 +1,9 @@
+export declare class PaymentCorrelations {
+    #private;
+    readonly nowSeconds: () => number;
+    constructor(nowSeconds: () => number);
+    set(signature: string, receiptId: string, validBeforeSeconds: number): void;
+    restore(signature: string, receiptId: string, validBeforeSeconds: number): void;
+    get(signature: string): string | null;
+    deleteIf(signature: string, receiptId: string): void;
+}

package/dist/payment-correlation.js

@@ -0,0 +1,36 @@
+export class PaymentCorrelations {
+    nowSeconds;
+    #entries = new Map();
+    constructor(nowSeconds) {
+        this.nowSeconds = nowSeconds;
+    }
+    set(signature, receiptId, validBeforeSeconds) {
+        this.#prune();
+        this.#entries.set(signature.toLowerCase(), { receiptId, validBeforeSeconds });
+    }
+    restore(signature, receiptId, validBeforeSeconds) {
+        if (!/^0x[0-9a-fA-F]{130}$/.test(signature) ||
+            !/^\S{1,256}$/.test(receiptId) ||
+            !Number.isSafeInteger(validBeforeSeconds) ||
+            validBeforeSeconds < 1) {
+            throw new Error("The persisted payment correlation is invalid.");
+        }
+        this.set(signature, receiptId, Math.max(validBeforeSeconds, this.nowSeconds() + 3_600));
+    }
+    get(signature) {
+        this.#prune();
+        return this.#entries.get(signature.toLowerCase())?.receiptId ?? null;
+    }
+    deleteIf(signature, receiptId) {
+        const key = signature.toLowerCase();
+        if (this.#entries.get(key)?.receiptId === receiptId)
+            this.#entries.delete(key);
+    }
+    #prune() {
+        const now = this.nowSeconds();
+        for (const [signature, correlation] of this.#entries) {
+            if (correlation.validBeforeSeconds <= now)
+                this.#entries.delete(signature);
+        }
+    }
+}

package/dist/payment-envelope-capacity.d.ts

@@ -0,0 +1,2 @@
+import { type PaymentEnvelopeDocument } from "./payment-envelope-model.js";
+export declare function assertNewPaymentEnvelopeCapacity(document: PaymentEnvelopeDocument, key: string, requestFingerprint: string, timestamp: string): void;

package/dist/payment-envelope-capacity.js

@@ -0,0 +1,28 @@
+import { MAX_PAYMENT_ENVELOPE_RECORDS, MAX_PAYMENT_ENVELOPE_STORE_BYTES, PaymentEnvelopeStoreError, } from "./payment-envelope-model.js";
+const MAX_PAYMENT_SIGNATURE = "A".repeat(32_768);
+const MAX_RECEIPT_ID = "r".repeat(128);
+function capacityError() {
+    throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_CAPACITY", "The durable payment envelope store reached its capacity bound.");
+}
+export function assertNewPaymentEnvelopeCapacity(document, key, requestFingerprint, timestamp) {
+    if (Object.keys(document.records).length >= MAX_PAYMENT_ENVELOPE_RECORDS)
+        capacityError();
+    const worstCase = {
+        records: {
+            ...document.records,
+            [key]: {
+                createdAt: timestamp,
+                paymentSignature: MAX_PAYMENT_SIGNATURE,
+                receiptId: MAX_RECEIPT_ID,
+                requestFingerprint,
+                state: "pending",
+                updatedAt: timestamp,
+                validBefore: Number.MAX_SAFE_INTEGER,
+            },
+        },
+        version: 1,
+    };
+    if (Buffer.byteLength(JSON.stringify(worstCase)) > MAX_PAYMENT_ENVELOPE_STORE_BYTES) {
+        capacityError();
+    }
+}

package/dist/payment-envelope-disk.d.ts

@@ -0,0 +1,5 @@
+import { type PaymentEnvelopeDocument } from "./payment-envelope-model.js";
+export declare const PAYMENT_ENVELOPE_FILE = "payment-envelopes.v1.json";
+export declare function preparePaymentEnvelopeDirectory(directory: string): Promise<void>;
+export declare function readPaymentEnvelopeDocument(directory: string): Promise<PaymentEnvelopeDocument>;
+export declare function writePaymentEnvelopeDocument(directory: string, document: PaymentEnvelopeDocument): Promise<void>;

package/dist/payment-envelope-disk.js

@@ -0,0 +1,97 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { chmod, lstat, mkdir, open, rename, rm } from "node:fs/promises";
+import { TextDecoder } from "node:util";
+import { MAX_PAYMENT_ENVELOPE_STORE_BYTES, PaymentEnvelopeStoreError, parsePaymentEnvelopeDocument, } from "./payment-envelope-model.js";
+export const PAYMENT_ENVELOPE_FILE = "payment-envelopes.v1.json";
+function ioError() {
+    return new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_CORRUPT", "The durable payment envelope store could not be read safely.");
+}
+export async function preparePaymentEnvelopeDirectory(directory) {
+    try {
+        await mkdir(directory, { mode: 0o700, recursive: true });
+        const metadata = await lstat(directory);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink())
+            throw ioError();
+        await chmod(directory, 0o700);
+    }
+    catch {
+        throw ioError();
+    }
+}
+export async function readPaymentEnvelopeDocument(directory) {
+    const path = `${directory}/${PAYMENT_ENVELOPE_FILE}`;
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { records: {}, version: 1 };
+        throw ioError();
+    }
+    try {
+        await handle.chmod(0o600);
+        const metadata = await handle.stat();
+        if (!metadata.isFile())
+            throw ioError();
+        if (metadata.size > MAX_PAYMENT_ENVELOPE_STORE_BYTES) {
+            throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_OVERSIZE", "The durable payment envelope store exceeds its size bound.");
+        }
+        const chunks = [];
+        let length = 0;
+        while (true) {
+            const chunk = Buffer.allocUnsafe(64 * 1_024);
+            const { bytesRead } = await handle.read(chunk, 0, chunk.length, null);
+            if (bytesRead === 0)
+                break;
+            length += bytesRead;
+            if (length > MAX_PAYMENT_ENVELOPE_STORE_BYTES) {
+                throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_OVERSIZE", "The durable payment envelope store exceeds its size bound.");
+            }
+            chunks.push(chunk.subarray(0, bytesRead));
+        }
+        const text = new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks, length));
+        return parsePaymentEnvelopeDocument(JSON.parse(text));
+    }
+    catch (error) {
+        if (error instanceof PaymentEnvelopeStoreError)
+            throw error;
+        throw ioError();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function writePaymentEnvelopeDocument(directory, document) {
+    const contents = JSON.stringify(document);
+    if (Buffer.byteLength(contents) > MAX_PAYMENT_ENVELOPE_STORE_BYTES) {
+        throw new PaymentEnvelopeStoreError("PAYMENT_ENVELOPE_OVERSIZE", "The durable payment envelope store exceeds its size bound.");
+    }
+    const destination = `${directory}/${PAYMENT_ENVELOPE_FILE}`;
+    const temporary = `${destination}.tmp-${process.pid}-${randomUUID()}`;
+    let handle;
+    try {
+        handle = await open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        await handle.writeFile(contents, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await rename(temporary, destination);
+        await chmod(destination, 0o600);
+        const directoryHandle = await open(directory, constants.O_RDONLY);
+        try {
+            await directoryHandle.sync();
+        }
+        finally {
+            await directoryHandle.close();
+        }
+    }
+    catch (error) {
+        await handle?.close().catch(() => undefined);
+        await rm(temporary, { force: true }).catch(() => undefined);
+        if (error instanceof PaymentEnvelopeStoreError)
+            throw error;
+        throw ioError();
+    }
+}

package/dist/payment-envelope-journal.d.ts

@@ -0,0 +1,54 @@
+import { readPaymentAuthorizationState } from "./payment-authorization-state.js";
+import { parsePaymentEnvelope } from "./payment-envelope.js";
+import type { NewPaymentEnvelope, PaymentEnvelopeRecord, PaymentEnvelopeStore } from "./payment-envelope-store.js";
+import type { PaymentProfile } from "./payment-profile.js";
+import type { TabRemoteSigner } from "./remote-signer.js";
+export declare class PaymentIdempotencyRequiredError extends Error {
+    readonly code = "PAYMENT_IDEMPOTENCY_KEY_REQUIRED";
+    constructor();
+}
+export declare class PaymentReconciliationRequiredError extends Error {
+    readonly code = "PAYMENT_RECONCILIATION_REQUIRED";
+    constructor();
+}
+interface PaymentEnvelopeJournalOptions {
+    address: `0x${string}`;
+    authorizationState?: typeof readPaymentAuthorizationState;
+    nowSeconds?: () => number;
+    paymentProfile: PaymentProfile;
+    signer: TabRemoteSigner;
+    store: PaymentEnvelopeStore;
+}
+type ParsedEnvelope = Awaited<ReturnType<typeof parsePaymentEnvelope>>;
+type ParsedEnvelopePayload = Pick<ParsedEnvelope, "payload">;
+export declare class PaymentEnvelopeJournal {
+    #private;
+    constructor(options: PaymentEnvelopeJournalOptions);
+    load(idempotencyKey: string, requestFingerprint: string): Promise<PaymentEnvelopeRecord | null>;
+    getOrCreate(idempotencyKey: string, requestFingerprint: string, factory: () => Promise<NewPaymentEnvelope>): Promise<PaymentEnvelopeRecord>;
+    parse(envelope: PaymentEnvelopeRecord): Promise<{
+        asset: `0x${string}`;
+        from: `0x${string}`;
+        network: "eip155:8453" | "eip155:42161" | "eip155:84532";
+        nonce: `0x${string}`;
+        payload: import("@x402/mcp").PaymentPayload;
+        signature: `0x${string}`;
+        validBefore: number;
+    }>;
+    recordObservation(idempotencyKey: string, requestFingerprint: string, parsed: ParsedEnvelopePayload, value: unknown): Promise<PaymentEnvelopeRecord | null>;
+    reconcileObserved(idempotencyKey: string, requestFingerprint: string, envelope: PaymentEnvelopeRecord, parsed: ParsedEnvelopePayload): Promise<{
+        status: "failed";
+        verified: true;
+    } | {
+        status: "pending";
+        verified: false;
+    } | {
+        status: "settled";
+        verified: true;
+    } | {
+        readonly status: "ignored";
+        readonly verified: false;
+    }>;
+    markSettled(idempotencyKey: string, requestFingerprint: string): Promise<PaymentEnvelopeRecord>;
+}
+export {};