agentwallet-sdk 5.0.0 → 5.0.2

package/dist/policy/SpendingPolicy.js

@@ -0,0 +1,155 @@
+/**
+ * SpendingPolicy — Programmable spending guardrails for AI agents.
+ *
+ * Beats PolicyLayer.com to market with:
+ *   - MerchantAllowlist  — allowlist-only merchant enforcement
+ *   - RollingSpendCap    — time-windowed spend limits
+ *   - DraftThenApprove   — human-in-the-loop for large transactions
+ *   - AuditTrail         — immutable local log of every payment attempt
+ *   - FailClosed         — policy errors always reject, never approve
+ *
+ * @module policy/SpendingPolicy
+ */
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+let _idCounter = 0;
+function nextId(prefix) {
+    return `${prefix}-${Date.now()}-${++_idCounter}`;
+}
+// ─── SpendingPolicy ───────────────────────────────────────────────────────────
+export class SpendingPolicy {
+    constructor(config) {
+        this.config = config;
+        this.allowlist = new Set((config.merchantAllowlist ?? []).map((m) => m.toLowerCase()));
+        this.spendWindow = [];
+        this.auditLog = [];
+        this.drafts = new Map();
+    }
+    // ─── Public Interface ───────────────────────────────────────────────────────
+    /**
+     * FailClosed: wraps the actual check logic so that ANY unhandled error
+     * produces a rejection rather than inadvertently approving a payment.
+     */
+    async check(payment) {
+        try {
+            return await this._check(payment);
+        }
+        catch (err) {
+            const reason = `Policy engine error (fail-closed): ${err instanceof Error ? err.message : String(err)}`;
+            const result = { status: 'rejected', reason };
+            await this.log(payment, result).catch(() => { });
+            return result;
+        }
+    }
+    /**
+     * Write a payment attempt to the immutable audit log.
+     */
+    async log(payment, result) {
+        const entry = {
+            id: nextId('audit'),
+            timestamp: payment.timestamp ?? new Date().toISOString(),
+            merchant: payment.merchant,
+            amount: payment.amount,
+            status: result.status,
+            reason: result.reason,
+            draftId: result.draftId,
+        };
+        this.auditLog.push(entry);
+    }
+    /** Return a copy of the current merchant allowlist. */
+    getMerchantAllowlist() {
+        return Array.from(this.allowlist);
+    }
+    /** Add a merchant address/domain to the allowlist at runtime. */
+    addMerchant(address) {
+        this.allowlist.add(address.toLowerCase());
+    }
+    /** Return the full, immutable audit log (copy). */
+    getAuditLog() {
+        return [...this.auditLog];
+    }
+    // ─── Draft queue management ─────────────────────────────────────────────────
+    /** Approve a queued draft by its draftId. Returns false if not found. */
+    approveDraft(draftId) {
+        const draft = this.drafts.get(draftId);
+        if (!draft)
+            return false;
+        draft.approved = true;
+        return true;
+    }
+    /** Reject a queued draft by its draftId. Returns false if not found. */
+    rejectDraft(draftId) {
+        const draft = this.drafts.get(draftId);
+        if (!draft)
+            return false;
+        draft.rejected = true;
+        return true;
+    }
+    /** Return all pending (not yet approved or rejected) drafts. */
+    getPendingDrafts() {
+        return Array.from(this.drafts.values()).filter((d) => !d.approved && !d.rejected);
+    }
+    /** Return all drafts. */
+    getAllDrafts() {
+        return Array.from(this.drafts.values());
+    }
+    // ─── Private Logic ──────────────────────────────────────────────────────────
+    async _check(payment) {
+        // 1. MerchantAllowlist check (only enforced when allowlist is non-empty)
+        if (this.allowlist.size > 0) {
+            const merchant = payment.merchant.toLowerCase();
+            if (!this.allowlist.has(merchant)) {
+                const result = {
+                    status: 'rejected',
+                    reason: `Merchant "${payment.merchant}" is not on the allowlist.`,
+                };
+                await this.log(payment, result);
+                return result;
+            }
+        }
+        // 2. RollingSpendCap check
+        if (this.config.rollingCap) {
+            const { maxAmount, windowMs } = this.config.rollingCap;
+            const now = Date.now();
+            const windowStart = now - windowMs;
+            // Purge entries outside the window
+            this.spendWindow = this.spendWindow.filter((e) => e.ts >= windowStart);
+            const spent = this.spendWindow.reduce((sum, e) => sum + e.amount, 0);
+            if (spent + payment.amount > maxAmount) {
+                const result = {
+                    status: 'rejected',
+                    reason: `Rolling spend cap exceeded: spent ${spent}, cap ${maxAmount}, attempted ${payment.amount}.`,
+                };
+                await this.log(payment, result);
+                return result;
+            }
+        }
+        // 3. DraftThenApprove check
+        if (this.config.draftThreshold !== undefined &&
+            payment.amount >= this.config.draftThreshold) {
+            const draftId = nextId('draft');
+            const draft = {
+                draftId,
+                payment,
+                queuedAt: payment.timestamp ?? new Date().toISOString(),
+                approved: false,
+                rejected: false,
+            };
+            this.drafts.set(draftId, draft);
+            const result = {
+                status: 'draft',
+                reason: `Amount ${payment.amount} meets or exceeds draft threshold ${this.config.draftThreshold}. Awaiting approval.`,
+                draftId,
+            };
+            await this.log(payment, result);
+            return result;
+        }
+        // 4. Approved — record spend in rolling window
+        if (this.config.rollingCap) {
+            this.spendWindow.push({ amount: payment.amount, ts: Date.now() });
+        }
+        const result = { status: 'approved' };
+        await this.log(payment, result);
+        return result;
+    }
+}
+//# sourceMappingURL=SpendingPolicy.js.map

package/dist/policy/SpendingPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpendingPolicy.js","sourceRoot":"","sources":["../../src/policy/SpendingPolicy.ts"],"names":[],"mappings":"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"}

package/dist/policy/SpendingPolicy.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=SpendingPolicy.test.d.ts.map

package/dist/policy/SpendingPolicy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpendingPolicy.test.d.ts","sourceRoot":"","sources":["../../src/policy/SpendingPolicy.test.ts"],"names":[],"mappings":""}

package/dist/policy/SpendingPolicy.test.js

@@ -0,0 +1,143 @@
+import { describe, it, expect } from 'vitest';
+import { SpendingPolicy } from './SpendingPolicy.js';
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+function makePayment(overrides = {}) {
+    return {
+        merchant: '0xAllowedMerchant',
+        amount: 10,
+        ...overrides,
+    };
+}
+function makePolicy(config) {
+    return new SpendingPolicy(config);
+}
+// ─── MerchantAllowlist ────────────────────────────────────────────────────────
+describe('MerchantAllowlist', () => {
+    it('allowlisted merchant passes', async () => {
+        const policy = makePolicy({ merchantAllowlist: ['0xallowedmerchant'] });
+        const result = await policy.check(makePayment({ merchant: '0xAllowedMerchant' }));
+        expect(result.status).toBe('approved');
+    });
+    it('non-allowlisted merchant is blocked', async () => {
+        const policy = makePolicy({ merchantAllowlist: ['0xallowedmerchant'] });
+        const result = await policy.check(makePayment({ merchant: '0xEvilMerchant' }));
+        expect(result.status).toBe('rejected');
+        expect(result.reason).toMatch(/not on the allowlist/i);
+    });
+    it('addMerchant allows previously blocked merchant', async () => {
+        const policy = makePolicy({ merchantAllowlist: ['0xallowedmerchant'] });
+        policy.addMerchant('0xNewMerchant');
+        const result = await policy.check(makePayment({ merchant: '0xNewMerchant' }));
+        expect(result.status).toBe('approved');
+    });
+    it('getMerchantAllowlist returns current allowlist', () => {
+        const policy = makePolicy({ merchantAllowlist: ['0xA', '0xB'] });
+        const list = policy.getMerchantAllowlist();
+        expect(list).toContain('0xa');
+        expect(list).toContain('0xb');
+        expect(list.length).toBe(2);
+    });
+});
+// ─── RollingSpendCap ──────────────────────────────────────────────────────────
+describe('RollingSpendCap', () => {
+    it('allows payment under the rolling cap', async () => {
+        const policy = makePolicy({
+            rollingCap: { maxAmount: 100, windowMs: 86400000 },
+        });
+        const result = await policy.check(makePayment({ amount: 50 }));
+        expect(result.status).toBe('approved');
+    });
+    it('blocks payment that would exceed the rolling cap', async () => {
+        const policy = makePolicy({
+            rollingCap: { maxAmount: 100, windowMs: 86400000 },
+        });
+        // First spend: 80
+        await policy.check(makePayment({ amount: 80 }));
+        // Second spend: 30 — total 110 > 100
+        const result = await policy.check(makePayment({ amount: 30 }));
+        expect(result.status).toBe('rejected');
+        expect(result.reason).toMatch(/rolling spend cap exceeded/i);
+    });
+    it('allows payment exactly at the rolling cap', async () => {
+        const policy = makePolicy({
+            rollingCap: { maxAmount: 100, windowMs: 86400000 },
+        });
+        await policy.check(makePayment({ amount: 50 }));
+        const result = await policy.check(makePayment({ amount: 50 }));
+        expect(result.status).toBe('approved');
+    });
+});
+// ─── DraftThenApprove ─────────────────────────────────────────────────────────
+describe('DraftThenApprove', () => {
+    it('queues payment at or above draft threshold', async () => {
+        const policy = makePolicy({ draftThreshold: 500 });
+        const result = await policy.check(makePayment({ amount: 500 }));
+        expect(result.status).toBe('draft');
+        expect(result.draftId).toBeTruthy();
+    });
+    it('approves payment below draft threshold immediately', async () => {
+        const policy = makePolicy({ draftThreshold: 500 });
+        const result = await policy.check(makePayment({ amount: 499 }));
+        expect(result.status).toBe('approved');
+    });
+    it('queued draft appears in getPendingDrafts()', async () => {
+        const policy = makePolicy({ draftThreshold: 100 });
+        const result = await policy.check(makePayment({ amount: 200 }));
+        const pending = policy.getPendingDrafts();
+        expect(pending.length).toBe(1);
+        expect(pending[0].draftId).toBe(result.draftId);
+    });
+    it('approveDraft marks draft approved and removes from pending', async () => {
+        const policy = makePolicy({ draftThreshold: 100 });
+        const result = await policy.check(makePayment({ amount: 200 }));
+        const draftId = result.draftId;
+        expect(policy.approveDraft(draftId)).toBe(true);
+        expect(policy.getPendingDrafts().length).toBe(0);
+        const draft = policy.getAllDrafts().find((d) => d.draftId === draftId);
+        expect(draft.approved).toBe(true);
+    });
+});
+// ─── AuditTrail ───────────────────────────────────────────────────────────────
+describe('AuditTrail', () => {
+    it('creates an audit entry for every payment attempt', async () => {
+        const policy = makePolicy({});
+        await policy.check(makePayment({ amount: 10 }));
+        await policy.check(makePayment({ amount: 20 }));
+        const log = policy.getAuditLog();
+        expect(log.length).toBe(2);
+    });
+    it('audit entry records merchant, amount, and status', async () => {
+        const policy = makePolicy({ merchantAllowlist: ['0xgood'] });
+        await policy.check(makePayment({ merchant: '0xBad', amount: 99 }));
+        const entry = policy.getAuditLog()[0];
+        expect(entry.merchant).toBe('0xBad');
+        expect(entry.amount).toBe(99);
+        expect(entry.status).toBe('rejected');
+    });
+    it('audit log is append-only (getAuditLog returns copy)', async () => {
+        const policy = makePolicy({});
+        await policy.check(makePayment());
+        const log = policy.getAuditLog();
+        log.push({ id: 'tamper', timestamp: '', merchant: '', amount: 0, status: 'approved' });
+        // Original log should still have only 1 entry
+        expect(policy.getAuditLog().length).toBe(1);
+    });
+});
+// ─── FailClosed ───────────────────────────────────────────────────────────────
+describe('FailClosed', () => {
+    it('rejects payment when policy engine throws an error', async () => {
+        const policy = makePolicy({ merchantAllowlist: ['0xgood'] });
+        // Corrupt internal state to trigger an error inside _check
+        // We spy on the private method by monkey-patching to throw
+        const original = policy._check.bind(policy);
+        policy._check = async () => {
+            throw new Error('Simulated internal policy crash');
+        };
+        const result = await policy.check(makePayment());
+        expect(result.status).toBe('rejected');
+        expect(result.reason).toMatch(/fail-closed/i);
+        // Restore
+        policy._check = original;
+    });
+});
+//# sourceMappingURL=SpendingPolicy.test.js.map

package/dist/policy/SpendingPolicy.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpendingPolicy.test.js","sourceRoot":"","sources":["../../src/policy/SpendingPolicy.test.ts"],"names":[],"mappings":"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"}

package/dist/settlement/index.d.ts

@@ -0,0 +1,4 @@
+export { SettlementVerifier } from './verifier.js';
+export type { SettlementVerifierConfig, SettlementStatus, SettlementResult, BridgeSettlementResult, BridgeSettlementStatus, PaymentSettlementResult, } from './types.js';
+export { SETTLEMENT_ALCHEMY_NETWORKS, SETTLEMENT_PUBLIC_RPCS, CIRCLE_ATTESTATION_API, ERC20_TRANSFER_TOPIC, SOLANA_RPC_URL, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/settlement/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/settlement/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACnD,YAAY,EACV,wBAAwB,EACxB,gBAAgB,EAChB,gBAAgB,EAChB,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/settlement/index.js

@@ -0,0 +1,3 @@
+export { SettlementVerifier } from './verifier.js';
+export { SETTLEMENT_ALCHEMY_NETWORKS, SETTLEMENT_PUBLIC_RPCS, CIRCLE_ATTESTATION_API, ERC20_TRANSFER_TOPIC, SOLANA_RPC_URL, } from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/settlement/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/settlement/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AASnD,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,EACtB,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/settlement/types.d.ts

@@ -0,0 +1,66 @@
+export interface SettlementVerifierConfig {
+    /** Alchemy API key (optional — falls back to public RPC if not provided) */
+    alchemyApiKey?: string;
+}
+/** Status of an on-chain settlement */
+export type SettlementStatus = 'confirmed' | 'pending' | 'failed' | 'not_found';
+/** Result of verifying a single transaction */
+export interface SettlementResult {
+    status: SettlementStatus;
+    txHash: string;
+    /** Block number where the tx was included (0 if pending/not found) */
+    blockNumber: bigint;
+    /** Number of confirmations at query time */
+    confirmations: number;
+    /** Gas used by the transaction */
+    gasUsed?: bigint;
+    /** Whether the tx succeeded (status=1) or reverted (status=0) */
+    success?: boolean;
+    /** Any error message if verification failed */
+    error?: string;
+}
+/** Result of verifying a CCTP bridge transfer end-to-end */
+export interface BridgeSettlementResult {
+    /** Overall bridge status */
+    status: BridgeSettlementStatus;
+    /** Source chain burn transaction */
+    sourceTx: SettlementResult;
+    /** Destination chain mint transaction (if found) */
+    destinationTx?: SettlementResult;
+    /** Circle attestation status */
+    attestationStatus?: 'pending_confirmations' | 'complete' | 'error';
+    /** Amount that was bridged (from source tx logs) */
+    amount?: bigint;
+    /** Destination address that received funds */
+    recipient?: string;
+    /** Any error or warning messages */
+    error?: string;
+}
+export type BridgeSettlementStatus = 'source_confirmed_awaiting_attestation' | 'attestation_complete_awaiting_mint' | 'complete' | 'source_failed' | 'source_pending' | 'not_found' | 'error';
+/** Result of verifying an x402 payment */
+export interface PaymentSettlementResult {
+    status: SettlementStatus;
+    txHash: string;
+    /** Whether the payment went to the expected payee */
+    payeeVerified: boolean;
+    /** Whether the amount matches */
+    amountVerified: boolean;
+    /** Actual amount transferred (from event logs) */
+    actualAmount?: bigint;
+    /** Actual payee address (from event logs) */
+    actualPayee?: string;
+    /** Token contract address */
+    tokenAddress?: string;
+    error?: string;
+}
+/** Alchemy network slugs for settlement verification (subset: EVM chains with Alchemy support) */
+export declare const SETTLEMENT_ALCHEMY_NETWORKS: Record<string, string>;
+/** Public RPC fallbacks for chains without Alchemy Gas Manager support */
+export declare const SETTLEMENT_PUBLIC_RPCS: Record<string, string>;
+/** Circle CCTP attestation API base URL */
+export declare const CIRCLE_ATTESTATION_API = "https://iris-api.circle.com/attestations";
+/** ERC20 Transfer event topic: keccak256("Transfer(address,address,uint256)") */
+export declare const ERC20_TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+/** Solana RPC endpoint */
+export declare const SOLANA_RPC_URL = "https://api.mainnet-beta.solana.com";
+//# sourceMappingURL=types.d.ts.map

package/dist/settlement/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/settlement/types.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,uCAAuC;AACvC,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEhF,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,aAAa,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,4DAA4D;AAC5D,MAAM,WAAW,sBAAsB;IACrC,4BAA4B;IAC5B,MAAM,EAAE,sBAAsB,CAAC;IAC/B,oCAAoC;IACpC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,oDAAoD;IACpD,aAAa,CAAC,EAAE,gBAAgB,CAAC;IACjC,gCAAgC;IAChC,iBAAiB,CAAC,EAAE,uBAAuB,GAAG,UAAU,GAAG,OAAO,CAAC;IACnE,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,sBAAsB,GAC9B,uCAAuC,GACvC,oCAAoC,GACpC,UAAU,GACV,eAAe,GACf,gBAAgB,GAChB,WAAW,GACX,OAAO,CAAC;AAEZ,0CAA0C;AAC1C,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,aAAa,EAAE,OAAO,CAAC;IACvB,iCAAiC;IACjC,cAAc,EAAE,OAAO,CAAC;IACxB,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,kGAAkG;AAClG,eAAO,MAAM,2BAA2B,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAO9D,CAAC;AAEF,0EAA0E;AAC1E,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiBzD,CAAC;AAEF,2CAA2C;AAC3C,eAAO,MAAM,sBAAsB,6CAA6C,CAAC;AAEjF,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,uEACqC,CAAC;AAEvE,0BAA0B;AAC1B,eAAO,MAAM,cAAc,wCAAwC,CAAC"}

package/dist/settlement/types.js

@@ -0,0 +1,37 @@
+// Settlement Verification — Types
+// Verify that transactions, bridge transfers, and x402 payments actually settled on-chain.
+/** Alchemy network slugs for settlement verification (subset: EVM chains with Alchemy support) */
+export const SETTLEMENT_ALCHEMY_NETWORKS = {
+    ethereum: 'eth-mainnet',
+    base: 'base-mainnet',
+    arbitrum: 'arb-mainnet',
+    optimism: 'opt-mainnet',
+    polygon: 'polygon-mainnet',
+    worldchain: 'worldchain-mainnet',
+};
+/** Public RPC fallbacks for chains without Alchemy Gas Manager support */
+export const SETTLEMENT_PUBLIC_RPCS = {
+    ethereum: 'https://eth.llamarpc.com',
+    base: 'https://mainnet.base.org',
+    arbitrum: 'https://arb1.arbitrum.io/rpc',
+    optimism: 'https://mainnet.optimism.io',
+    polygon: 'https://polygon-rpc.com',
+    worldchain: 'https://worldchain-mainnet.g.alchemy.com/public',
+    avalanche: 'https://api.avax.network/ext/bc/C/rpc',
+    unichain: 'https://mainnet.unichain.org',
+    linea: 'https://rpc.linea.build',
+    sonic: 'https://rpc.soniclabs.com',
+    sei: 'https://evm-rpc.sei-apis.com',
+    ink: 'https://rpc-gel.inkonchain.com',
+    hyperevm: 'https://rpc.hyperliquid.xyz/evm',
+    plume: 'https://rpc.plumenetwork.xyz',
+    xdc: 'https://rpc.xinfin.network',
+    codex: 'https://rpc.codex.storage',
+};
+/** Circle CCTP attestation API base URL */
+export const CIRCLE_ATTESTATION_API = 'https://iris-api.circle.com/attestations';
+/** ERC20 Transfer event topic: keccak256("Transfer(address,address,uint256)") */
+export const ERC20_TRANSFER_TOPIC = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';
+/** Solana RPC endpoint */
+export const SOLANA_RPC_URL = 'https://api.mainnet-beta.solana.com';
+//# sourceMappingURL=types.js.map

package/dist/settlement/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/settlement/types.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,2FAA2F;AAsE3F,kGAAkG;AAClG,MAAM,CAAC,MAAM,2BAA2B,GAA2B;IACjE,QAAQ,EAAE,aAAa;IACvB,IAAI,EAAE,cAAc;IACpB,QAAQ,EAAE,aAAa;IACvB,QAAQ,EAAE,aAAa;IACvB,OAAO,EAAE,iBAAiB;IAC1B,UAAU,EAAE,oBAAoB;CACjC,CAAC;AAEF,0EAA0E;AAC1E,MAAM,CAAC,MAAM,sBAAsB,GAA2B;IAC5D,QAAQ,EAAE,0BAA0B;IACpC,IAAI,EAAE,0BAA0B;IAChC,QAAQ,EAAE,8BAA8B;IACxC,QAAQ,EAAE,6BAA6B;IACvC,OAAO,EAAE,yBAAyB;IAClC,UAAU,EAAE,iDAAiD;IAC7D,SAAS,EAAE,uCAAuC;IAClD,QAAQ,EAAE,8BAA8B;IACxC,KAAK,EAAE,yBAAyB;IAChC,KAAK,EAAE,2BAA2B;IAClC,GAAG,EAAE,8BAA8B;IACnC,GAAG,EAAE,gCAAgC;IACrC,QAAQ,EAAE,iCAAiC;IAC3C,KAAK,EAAE,8BAA8B;IACrC,GAAG,EAAE,4BAA4B;IACjC,KAAK,EAAE,2BAA2B;CACnC,CAAC;AAEF,2CAA2C;AAC3C,MAAM,CAAC,MAAM,sBAAsB,GAAG,0CAA0C,CAAC;AAEjF,iFAAiF;AACjF,MAAM,CAAC,MAAM,oBAAoB,GAC/B,oEAAoE,CAAC;AAEvE,0BAA0B;AAC1B,MAAM,CAAC,MAAM,cAAc,GAAG,qCAAqC,CAAC"}

package/dist/settlement/verifier.d.ts

@@ -0,0 +1,75 @@
+import type { SettlementVerifierConfig, SettlementResult, BridgeSettlementResult, PaymentSettlementResult } from './types.js';
+export declare class SettlementVerifier {
+    private readonly alchemyApiKey;
+    constructor(config?: SettlementVerifierConfig);
+    /**
+     * Verify that an EVM transaction settled on-chain.
+     *
+     * Uses Alchemy RPC if apiKey is configured and chain is supported,
+     * otherwise falls back to public RPCs.
+     *
+     * @param params.chain - SDK chain name (e.g. 'base', 'arbitrum')
+     * @param params.txHash - Transaction hash to verify
+     * @param params.confirmations - Minimum confirmations required (default: 1)
+     */
+    verifyEvmTransaction(params: {
+        chain: string;
+        txHash: string;
+        confirmations?: number;
+    }): Promise<SettlementResult>;
+    /**
+     * Verify that a Solana transaction settled on-chain.
+     *
+     * @param params.signature - Solana transaction signature (base58)
+     * @param params.commitment - Commitment level: 'confirmed' or 'finalized' (default: 'confirmed')
+     */
+    verifySolanaTransaction(params: {
+        signature: string;
+        commitment?: 'confirmed' | 'finalized';
+    }): Promise<SettlementResult>;
+    /**
+     * Verify a CCTP bridge transfer settled end-to-end:
+     *   1. Verifies source chain burn tx succeeded
+     *   2. Checks Circle attestation API for the message hash
+     *   3. Attempts to find destination mint tx (if attestation is complete)
+     *
+     * @param params.sourceTxHash - Burn tx hash on source chain
+     * @param params.sourceChain - Source chain name (e.g. 'solana', 'base')
+     * @param params.destinationChain - Destination chain name
+     * @param params.expectedAmount - Expected USDC amount in base units (6 decimals)
+     */
+    verifyBridgeSettlement(params: {
+        sourceTxHash: string;
+        sourceChain: string;
+        destinationChain: string;
+        expectedAmount: bigint;
+    }): Promise<BridgeSettlementResult>;
+    /**
+     * Verify an x402 payment settled on-chain by inspecting ERC20 Transfer event logs.
+     *
+     * Checks that the tx:
+     *   - Succeeded (status=1)
+     *   - Emitted an ERC20 Transfer event to expectedPayee
+     *   - The transferred amount matches expectedAmount
+     *
+     * @param params.chain - EVM chain name
+     * @param params.txHash - Transaction hash
+     * @param params.expectedPayee - Address that should have received the payment
+     * @param params.expectedAmount - Amount in USDC base units (6 decimals)
+     */
+    verifyX402Payment(params: {
+        chain: string;
+        txHash: string;
+        expectedPayee: string;
+        expectedAmount: bigint;
+    }): Promise<PaymentSettlementResult>;
+    /** Get the RPC URL for a chain, preferring Alchemy over public RPCs */
+    private _getRpcUrl;
+    /** Make an EVM JSON-RPC call */
+    private _evmRpc;
+    /** Make a Solana JSON-RPC call */
+    private _solanaRpc;
+    /** Check Circle attestation API for a CCTP burn message */
+    private _checkCircleAttestation;
+}
+//# sourceMappingURL=verifier.d.ts.map

package/dist/settlement/verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/settlement/verifier.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EACV,wBAAwB,EACxB,gBAAgB,EAChB,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AASpB,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;gBAEvC,MAAM,GAAE,wBAA6B;IAMjD;;;;;;;;;OASG;IACG,oBAAoB,CAAC,MAAM,EAAE;QACjC,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IA2E7B;;;;;OAKG;IACG,uBAAuB,CAAC,MAAM,EAAE;QACpC,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,WAAW,GAAG,WAAW,CAAC;KACxC,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqD7B;;;;;;;;;;OAUG;IACG,sBAAsB,CAAC,MAAM,EAAE;QACnC,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,CAAC;QACzB,cAAc,EAAE,MAAM,CAAC;KACxB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAkEnC;;;;;;;;;;;;OAYG;IACG,iBAAiB,CAAC,MAAM,EAAE;QAC9B,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,CAAC;QACtB,cAAc,EAAE,MAAM,CAAC;KACxB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAqFpC,uEAAuE;IACvE,OAAO,CAAC,UAAU;IAYlB,gCAAgC;YAClB,OAAO;IAoBrB,kCAAkC;YACpB,UAAU;IAmBxB,2DAA2D;YAC7C,uBAAuB;CA0BtC"}