crumb-alpha-core 0.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> crumb-alpha-core@0.1.0 build /Users/taylorferran/Desktop/dev/crumb-sdk/packages/core
+> tsc
+

package/.turbo/turbo-test.log

@@ -0,0 +1,34 @@
+
+
+> @crumb/core@0.1.0 test /Users/taylorferran/Desktop/dev/crumb-sdk/packages/core
+> vitest run
+
+[?25l
+ RUN  v4.0.18 /Users/taylorferran/Desktop/dev/crumb-sdk/packages/core
+
+[?2026h
+ ❯ test/payment402.test.ts [queued]
+
+ Test Files 0 passed (5)
+      Tests 0 passed (0)
+   Start at 11:08:53
+   Duration 101ms
+[?2026l[?2026h ✓ test/errors.test.ts (6 tests) 2ms
+ ✓ test/balance.test.ts (3 tests) 2ms
+ ✓ test/payment402.test.ts (7 tests) 3ms
+ ✓ test/settlement.test.ts (6 tests) 4ms
+
+ ❯ test/wallet.test.ts 1/8
+
+ Test Files 4 passed (5)
+      Tests 23 passed (30)
+   Start at 11:08:53
+   Duration 202ms
+[?2026l ✓ test/wallet.test.ts (8 tests) 24ms
+
+ Test Files  5 passed (5)
+      Tests  30 passed (30)
+   Start at  11:08:53
+   Duration  237ms (transform 170ms, setup 0ms, import 258ms, tests 35ms, environment 0ms)
+
+[?25h

package/dist/balance.d.ts

@@ -0,0 +1,5 @@
+import type { SupportedChainName, Balances } from '@circle-fin/x402-batching/client';
+import type { CrumbWallet } from './types.js';
+export declare function getBalances(wallet: CrumbWallet, chain?: SupportedChainName): Promise<Balances>;
+export declare function getBalancesForAddress(wallet: CrumbWallet, address: string, chain?: SupportedChainName): Promise<Balances>;
+//# sourceMappingURL=balance.d.ts.map

package/dist/balance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance.d.ts","sourceRoot":"","sources":["../src/balance.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAA;AACpF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,wBAAsB,WAAW,CAC/B,MAAM,EAAE,WAAW,EACnB,KAAK,GAAE,kBAAiC,GACvC,OAAO,CAAC,QAAQ,CAAC,CAMnB;AAED,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,kBAAiC,GACvC,OAAO,CAAC,QAAQ,CAAC,CAMnB"}

package/dist/balance.js

@@ -0,0 +1,16 @@
+import { GatewayClient } from '@circle-fin/x402-batching/client';
+export async function getBalances(wallet, chain = 'arcTestnet') {
+    const client = new GatewayClient({
+        chain,
+        privateKey: wallet.privateKey,
+    });
+    return client.getBalances();
+}
+export async function getBalancesForAddress(wallet, address, chain = 'arcTestnet') {
+    const client = new GatewayClient({
+        chain,
+        privateKey: wallet.privateKey,
+    });
+    return client.getBalances(address);
+}
+//# sourceMappingURL=balance.js.map

package/dist/balance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"balance.js","sourceRoot":"","sources":["../src/balance.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAA;AAIhE,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,MAAmB,EACnB,QAA4B,YAAY;IAExC,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC;QAC/B,KAAK;QACL,UAAU,EAAE,MAAM,CAAC,UAA2B;KAC/C,CAAC,CAAA;IACF,OAAO,MAAM,CAAC,WAAW,EAAE,CAAA;AAC7B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,MAAmB,EACnB,OAAe,EACf,QAA4B,YAAY;IAExC,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC;QAC/B,KAAK;QACL,UAAU,EAAE,MAAM,CAAC,UAA2B;KAC/C,CAAC,CAAA;IACF,OAAO,MAAM,CAAC,WAAW,CAAC,OAAwB,CAAC,CAAA;AACrD,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export type CrumbErrorCode = 'PRICE_EXCEEDED' | 'INSUFFICIENT_BALANCE' | 'VERIFY_FAILED' | 'SETTLE_FAILED' | 'INVALID_402' | 'NOT_402' | 'PAYMENT_REJECTED' | 'WALLET_NOT_FOUND' | 'NETWORK_ERROR';
+export declare class CrumbError extends Error {
+    code: CrumbErrorCode;
+    detail?: Record<string, any> | undefined;
+    constructor(code: CrumbErrorCode, detail?: Record<string, any> | undefined);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GACtB,gBAAgB,GAChB,sBAAsB,GACtB,eAAe,GACf,eAAe,GACf,aAAa,GACb,SAAS,GACT,kBAAkB,GAClB,kBAAkB,GAClB,eAAe,CAAA;AAEnB,qBAAa,UAAW,SAAQ,KAAK;IAE1B,IAAI,EAAE,cAAc;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;gBAD5B,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,YAAA;CAKtC"}

package/dist/errors.js

@@ -0,0 +1,11 @@
+export class CrumbError extends Error {
+    code;
+    detail;
+    constructor(code, detail) {
+        super(`[${code}] ${JSON.stringify(detail ?? {})}`);
+        this.code = code;
+        this.detail = detail;
+        this.name = 'CrumbError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,UAAW,SAAQ,KAAK;IAE1B;IACA;IAFT,YACS,IAAoB,EACpB,MAA4B;QAEnC,KAAK,CAAC,IAAI,IAAI,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC,CAAA;QAH3C,SAAI,GAAJ,IAAI,CAAgB;QACpB,WAAM,GAAN,MAAM,CAAsB;QAGnC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAA;IAC1B,CAAC;CACF"}

package/dist/gateway.d.ts

@@ -0,0 +1,6 @@
+import { GatewayClient } from '@circle-fin/x402-batching/client';
+import type { SupportedChainName, GatewayClientConfig } from '@circle-fin/x402-batching/client';
+export type { SupportedChainName, GatewayClientConfig };
+export { GatewayClient };
+export { CHAIN_CONFIGS, GATEWAY_DOMAINS } from '@circle-fin/x402-batching/client';
+//# sourceMappingURL=gateway.d.ts.map

package/dist/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAA;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAA;AAE/F,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,CAAA;AAGvD,OAAO,EAAE,aAAa,EAAE,CAAA;AAGxB,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAA"}

package/dist/gateway.js

@@ -0,0 +1,6 @@
+import { GatewayClient } from '@circle-fin/x402-batching/client';
+// Re-export GatewayClient so SDK and CLI can use it
+export { GatewayClient };
+// Re-export chain constants
+export { CHAIN_CONFIGS, GATEWAY_DOMAINS } from '@circle-fin/x402-batching/client';
+//# sourceMappingURL=gateway.js.map

package/dist/gateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.js","sourceRoot":"","sources":["../src/gateway.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAA;AAKhE,oDAAoD;AACpD,OAAO,EAAE,aAAa,EAAE,CAAA;AAExB,4BAA4B;AAC5B,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { CrumbWallet, SettlementResult, FetchOptions, FetchResult, MiddlewareConfig, SupportedChainName, Balances, PayResult, } from './types.js';
+export { CrumbError } from './errors.js';
+export type { CrumbErrorCode } from './errors.js';
+export { GatewayClient, CHAIN_CONFIGS, GATEWAY_DOMAINS, } from './gateway.js';
+export type { GatewayClientConfig } from './gateway.js';
+export { registerBatchScheme, BatchEvmScheme } from './signing.js';
+export { verifyPayment, settlePayment, verifyAndSettle, BatchFacilitatorClient } from './settlement.js';
+export { getBalances, getBalancesForAddress } from './balance.js';
+export { checkPriceCeiling } from './payment402.js';
+export { createWallet, walletFromPrivateKey, deriveAddress } from './wallet.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,QAAQ,EACR,SAAS,GACV,MAAM,YAAY,CAAA;AAGnB,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAGjD,OAAO,EACL,aAAa,EACb,aAAa,EACb,eAAe,GAChB,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAGvD,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAGlE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAGvG,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAGjE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAGnD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,15 @@
+// Errors
+export { CrumbError } from './errors.js';
+// Gateway Client
+export { GatewayClient, CHAIN_CONFIGS, GATEWAY_DOMAINS, } from './gateway.js';
+// Signing (advanced)
+export { registerBatchScheme, BatchEvmScheme } from './signing.js';
+// Settlement / Facilitator
+export { verifyPayment, settlePayment, verifyAndSettle, BatchFacilitatorClient } from './settlement.js';
+// Balance
+export { getBalances, getBalancesForAddress } from './balance.js';
+// 402 Payment parsing
+export { checkPriceCeiling } from './payment402.js';
+// Wallet
+export { createWallet, walletFromPrivateKey, deriveAddress } from './wallet.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,SAAS;AACT,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGxC,iBAAiB;AACjB,OAAO,EACL,aAAa,EACb,aAAa,EACb,eAAe,GAChB,MAAM,cAAc,CAAA;AAGrB,qBAAqB;AACrB,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAElE,2BAA2B;AAC3B,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AAEvG,UAAU;AACV,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AAEjE,sBAAsB;AACtB,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAEnD,SAAS;AACT,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA"}

package/dist/payment402.d.ts

@@ -0,0 +1,2 @@
+export declare function checkPriceCeiling(amount: string, maxPayment: number): void;
+//# sourceMappingURL=payment402.d.ts.map

package/dist/payment402.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment402.d.ts","sourceRoot":"","sources":["../src/payment402.ts"],"names":[],"mappings":"AAEA,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,IAAI,CAYN"}

package/dist/payment402.js

@@ -0,0 +1,15 @@
+import { CrumbError } from './errors.js';
+export function checkPriceCeiling(amount, maxPayment) {
+    // Strip $ prefix if present
+    const clean = amount.startsWith('$') ? amount.slice(1) : amount;
+    const quoted = parseFloat(clean);
+    if (isNaN(quoted))
+        return;
+    if (quoted > maxPayment) {
+        throw new CrumbError('PRICE_EXCEEDED', {
+            quoted,
+            ceiling: maxPayment,
+        });
+    }
+}
+//# sourceMappingURL=payment402.js.map

package/dist/payment402.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment402.js","sourceRoot":"","sources":["../src/payment402.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,MAAM,UAAU,iBAAiB,CAC/B,MAAc,EACd,UAAkB;IAElB,4BAA4B;IAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;IAC/D,MAAM,MAAM,GAAG,UAAU,CAAC,KAAK,CAAC,CAAA;IAChC,IAAI,KAAK,CAAC,MAAM,CAAC;QAAE,OAAM;IAEzB,IAAI,MAAM,GAAG,UAAU,EAAE,CAAC;QACxB,MAAM,IAAI,UAAU,CAAC,gBAAgB,EAAE;YACrC,MAAM;YACN,OAAO,EAAE,UAAU;SACpB,CAAC,CAAA;IACJ,CAAC;AACH,CAAC"}

package/dist/settlement.d.ts

@@ -0,0 +1,11 @@
+import { BatchFacilitatorClient } from '@circle-fin/x402-batching/server';
+import type { SettlementResult } from './types.js';
+export declare function verifyPayment(payload: any, requirements: any, facilitatorUrl?: string): Promise<{
+    isValid: boolean;
+    invalidReason?: string;
+    payer?: string;
+}>;
+export declare function settlePayment(payload: any, requirements: any, facilitatorUrl?: string): Promise<SettlementResult>;
+export declare function verifyAndSettle(payload: any, requirements: any, facilitatorUrl?: string): Promise<SettlementResult>;
+export { BatchFacilitatorClient };
+//# sourceMappingURL=settlement.d.ts.map

package/dist/settlement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement.d.ts","sourceRoot":"","sources":["../src/settlement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAA;AACzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAelD,wBAAsB,aAAa,CACjC,OAAO,EAAE,GAAG,EACZ,YAAY,EAAE,GAAG,EACjB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAWvE;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,GAAG,EACZ,YAAY,EAAE,GAAG,EACjB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAmB3B;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,GAAG,EACZ,YAAY,EAAE,GAAG,EACjB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,CAAC,CAG3B;AAED,OAAO,EAAE,sBAAsB,EAAE,CAAA"}

package/dist/settlement.js

@@ -0,0 +1,46 @@
+import { BatchFacilitatorClient } from '@circle-fin/x402-batching/server';
+import { CrumbError } from './errors.js';
+let defaultFacilitator = null;
+function getFacilitator(facilitatorUrl) {
+    if (facilitatorUrl) {
+        return new BatchFacilitatorClient({ url: facilitatorUrl });
+    }
+    if (!defaultFacilitator) {
+        defaultFacilitator = new BatchFacilitatorClient();
+    }
+    return defaultFacilitator;
+}
+export async function verifyPayment(payload, requirements, facilitatorUrl) {
+    const facilitator = getFacilitator(facilitatorUrl);
+    const result = await facilitator.verify(payload, requirements);
+    if (!result.isValid) {
+        throw new CrumbError('VERIFY_FAILED', {
+            reason: result.invalidReason,
+        });
+    }
+    return result;
+}
+export async function settlePayment(payload, requirements, facilitatorUrl) {
+    const facilitator = getFacilitator(facilitatorUrl);
+    const result = await facilitator.settle(payload, requirements);
+    if (!result.success) {
+        throw new CrumbError('SETTLE_FAILED', {
+            errorReason: result.errorReason,
+        });
+    }
+    return {
+        success: true,
+        txHash: result.transaction,
+        amount: requirements.amount ?? '0',
+        formattedAmount: requirements.amount ?? '0',
+        network: result.network,
+        payer: result.payer,
+        timestamp: new Date().toISOString(),
+    };
+}
+export async function verifyAndSettle(payload, requirements, facilitatorUrl) {
+    await verifyPayment(payload, requirements, facilitatorUrl);
+    return settlePayment(payload, requirements, facilitatorUrl);
+}
+export { BatchFacilitatorClient };
+//# sourceMappingURL=settlement.js.map

package/dist/settlement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement.js","sourceRoot":"","sources":["../src/settlement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAA;AAEzE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,IAAI,kBAAkB,GAAkC,IAAI,CAAA;AAE5D,SAAS,cAAc,CAAC,cAAuB;IAC7C,IAAI,cAAc,EAAE,CAAC;QACnB,OAAO,IAAI,sBAAsB,CAAC,EAAE,GAAG,EAAE,cAAc,EAAE,CAAC,CAAA;IAC5D,CAAC;IACD,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACxB,kBAAkB,GAAG,IAAI,sBAAsB,EAAE,CAAA;IACnD,CAAC;IACD,OAAO,kBAAkB,CAAA;AAC3B,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAY,EACZ,YAAiB,EACjB,cAAuB;IAEvB,MAAM,WAAW,GAAG,cAAc,CAAC,cAAc,CAAC,CAAA;IAClD,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;IAE9D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,UAAU,CAAC,eAAe,EAAE;YACpC,MAAM,EAAE,MAAM,CAAC,aAAa;SAC7B,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAY,EACZ,YAAiB,EACjB,cAAuB;IAEvB,MAAM,WAAW,GAAG,cAAc,CAAC,cAAc,CAAC,CAAA;IAClD,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;IAE9D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,UAAU,CAAC,eAAe,EAAE;YACpC,WAAW,EAAE,MAAM,CAAC,WAAW;SAChC,CAAC,CAAA;IACJ,CAAC;IAED,OAAO;QACL,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,MAAM,CAAC,WAAW;QAC1B,MAAM,EAAE,YAAY,CAAC,MAAM,IAAI,GAAG;QAClC,eAAe,EAAE,YAAY,CAAC,MAAM,IAAI,GAAG;QAC3C,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,KAAK,EAAE,MAAM,CAAC,KAAK;QACnB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACpC,CAAA;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAY,EACZ,YAAiB,EACjB,cAAuB;IAEvB,MAAM,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,cAAc,CAAC,CAAA;IAC1D,OAAO,aAAa,CAAC,OAAO,EAAE,YAAY,EAAE,cAAc,CAAC,CAAA;AAC7D,CAAC;AAED,OAAO,EAAE,sBAAsB,EAAE,CAAA"}

package/dist/signing.d.ts

@@ -0,0 +1,2 @@
+export { registerBatchScheme, BatchEvmScheme } from '@circle-fin/x402-batching/client';
+//# sourceMappingURL=signing.d.ts.map

package/dist/signing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.d.ts","sourceRoot":"","sources":["../src/signing.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA"}

package/dist/signing.js

@@ -0,0 +1,4 @@
+// Signing is handled internally by GatewayClient via BatchEvmScheme.
+// This module re-exports the registration helper for advanced use cases.
+export { registerBatchScheme, BatchEvmScheme } from '@circle-fin/x402-batching/client';
+//# sourceMappingURL=signing.js.map

package/dist/signing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signing.js","sourceRoot":"","sources":["../src/signing.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,yEAAyE;AAEzE,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA"}

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+import type { SupportedChainName, Balances, PayResult } from '@circle-fin/x402-batching/client';
+export type { SupportedChainName, Balances, PayResult };
+export interface CrumbWallet {
+    address: string;
+    privateKey: string;
+}
+export interface SettlementResult {
+    success: boolean;
+    txHash: string;
+    amount: string;
+    formattedAmount: string;
+    network: string;
+    payer?: string;
+    timestamp: string;
+}
+export interface FetchOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    body?: unknown;
+    headers?: Record<string, string>;
+    maxPayment?: number;
+    metadata?: Record<string, string>;
+}
+export interface FetchResult<T = unknown> {
+    data: T;
+    amount: bigint;
+    formattedAmount: string;
+    txHash: string;
+    status: number;
+}
+export interface MiddlewareConfig {
+    sellerAddress: string;
+    networks?: string | string[];
+    facilitatorUrl?: string;
+    description?: string;
+    onPayment?: (payment: {
+        verified: boolean;
+        payer: string;
+        amount: string;
+        network: string;
+        transaction?: string;
+    }) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAA;AAE/F,YAAY,EAAE,kBAAkB,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAA;AAEvD,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,eAAe,EAAE,MAAM,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAA;IAC1C,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAED,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,IAAI,EAAE,CAAC,CAAA;IACP,MAAM,EAAE,MAAM,CAAA;IACd,eAAe,EAAE,MAAM,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IAC5B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE;QACpB,QAAQ,EAAE,OAAO,CAAA;QACjB,KAAK,EAAE,MAAM,CAAA;QACb,MAAM,EAAE,MAAM,CAAA;QACd,OAAO,EAAE,MAAM,CAAA;QACf,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,KAAK,IAAI,CAAA;CACX"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/wallet.d.ts

@@ -0,0 +1,5 @@
+import type { CrumbWallet } from './types.js';
+export declare function createWallet(): CrumbWallet;
+export declare function walletFromPrivateKey(privateKey: string): CrumbWallet;
+export declare function deriveAddress(privateKey: string): string;
+//# sourceMappingURL=wallet.d.ts.map

package/dist/wallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.d.ts","sourceRoot":"","sources":["../src/wallet.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE7C,wBAAgB,YAAY,IAAI,WAAW,CAO1C;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CAMpE;AAED,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAGxD"}

package/dist/wallet.js

@@ -0,0 +1,21 @@
+import { privateKeyToAccount, generatePrivateKey } from 'viem/accounts';
+export function createWallet() {
+    const privateKey = generatePrivateKey();
+    const account = privateKeyToAccount(privateKey);
+    return {
+        address: account.address,
+        privateKey,
+    };
+}
+export function walletFromPrivateKey(privateKey) {
+    const account = privateKeyToAccount(privateKey);
+    return {
+        address: account.address,
+        privateKey,
+    };
+}
+export function deriveAddress(privateKey) {
+    const account = privateKeyToAccount(privateKey);
+    return account.address;
+}
+//# sourceMappingURL=wallet.js.map

package/dist/wallet.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wallet.js","sourceRoot":"","sources":["../src/wallet.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAGvE,MAAM,UAAU,YAAY;IAC1B,MAAM,UAAU,GAAG,kBAAkB,EAAE,CAAA;IACvC,MAAM,OAAO,GAAG,mBAAmB,CAAC,UAAU,CAAC,CAAA;IAC/C,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,UAAU;KACX,CAAA;AACH,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,UAAkB;IACrD,MAAM,OAAO,GAAG,mBAAmB,CAAC,UAA2B,CAAC,CAAA;IAChE,OAAO;QACL,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,UAAU;KACX,CAAA;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,UAAkB;IAC9C,MAAM,OAAO,GAAG,mBAAmB,CAAC,UAA2B,CAAC,CAAA;IAChE,OAAO,OAAO,CAAC,OAAO,CAAA;AACxB,CAAC"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "crumb-alpha-core",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@circle-fin/x402-batching": "^2.0.4",
+    "viem": "^2.23.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "test": "vitest run"
+  }
+}

package/src/balance.ts

@@ -0,0 +1,26 @@
+import { GatewayClient } from '@circle-fin/x402-batching/client'
+import type { SupportedChainName, Balances } from '@circle-fin/x402-batching/client'
+import type { CrumbWallet } from './types.js'
+
+export async function getBalances(
+  wallet: CrumbWallet,
+  chain: SupportedChainName = 'arcTestnet',
+): Promise<Balances> {
+  const client = new GatewayClient({
+    chain,
+    privateKey: wallet.privateKey as `0x${string}`,
+  })
+  return client.getBalances()
+}
+
+export async function getBalancesForAddress(
+  wallet: CrumbWallet,
+  address: string,
+  chain: SupportedChainName = 'arcTestnet',
+): Promise<Balances> {
+  const client = new GatewayClient({
+    chain,
+    privateKey: wallet.privateKey as `0x${string}`,
+  })
+  return client.getBalances(address as `0x${string}`)
+}

package/src/errors.ts

@@ -0,0 +1,20 @@
+export type CrumbErrorCode =
+  | 'PRICE_EXCEEDED' // quoted price > maxPayment ceiling
+  | 'INSUFFICIENT_BALANCE' // not enough funds
+  | 'VERIFY_FAILED' // facilitator.verify() rejected the payload
+  | 'SETTLE_FAILED' // facilitator.settle() returned failure
+  | 'INVALID_402' // provider returned malformed 402 payload
+  | 'NOT_402' // expected 402, got something else
+  | 'PAYMENT_REJECTED' // provider rejected payment header on retry
+  | 'WALLET_NOT_FOUND' // no wallet configured
+  | 'NETWORK_ERROR' // connectivity issue
+
+export class CrumbError extends Error {
+  constructor(
+    public code: CrumbErrorCode,
+    public detail?: Record<string, any>,
+  ) {
+    super(`[${code}] ${JSON.stringify(detail ?? {})}`)
+    this.name = 'CrumbError'
+  }
+}

package/src/gateway.ts

@@ -0,0 +1,10 @@
+import { GatewayClient } from '@circle-fin/x402-batching/client'
+import type { SupportedChainName, GatewayClientConfig } from '@circle-fin/x402-batching/client'
+
+export type { SupportedChainName, GatewayClientConfig }
+
+// Re-export GatewayClient so SDK and CLI can use it
+export { GatewayClient }
+
+// Re-export chain constants
+export { CHAIN_CONFIGS, GATEWAY_DOMAINS } from '@circle-fin/x402-batching/client'

package/src/index.ts

@@ -0,0 +1,38 @@
+// Types
+export type {
+  CrumbWallet,
+  SettlementResult,
+  FetchOptions,
+  FetchResult,
+  MiddlewareConfig,
+  SupportedChainName,
+  Balances,
+  PayResult,
+} from './types.js'
+
+// Errors
+export { CrumbError } from './errors.js'
+export type { CrumbErrorCode } from './errors.js'
+
+// Gateway Client
+export {
+  GatewayClient,
+  CHAIN_CONFIGS,
+  GATEWAY_DOMAINS,
+} from './gateway.js'
+export type { GatewayClientConfig } from './gateway.js'
+
+// Signing (advanced)
+export { registerBatchScheme, BatchEvmScheme } from './signing.js'
+
+// Settlement / Facilitator
+export { verifyPayment, settlePayment, verifyAndSettle, BatchFacilitatorClient } from './settlement.js'
+
+// Balance
+export { getBalances, getBalancesForAddress } from './balance.js'
+
+// 402 Payment parsing
+export { checkPriceCeiling } from './payment402.js'
+
+// Wallet
+export { createWallet, walletFromPrivateKey, deriveAddress } from './wallet.js'

package/src/payment402.ts

@@ -0,0 +1,18 @@
+import { CrumbError } from './errors.js'
+
+export function checkPriceCeiling(
+  amount: string,
+  maxPayment: number,
+): void {
+  // Strip $ prefix if present
+  const clean = amount.startsWith('$') ? amount.slice(1) : amount
+  const quoted = parseFloat(clean)
+  if (isNaN(quoted)) return
+
+  if (quoted > maxPayment) {
+    throw new CrumbError('PRICE_EXCEEDED', {
+      quoted,
+      ceiling: maxPayment,
+    })
+  }
+}

package/src/settlement.ts

@@ -0,0 +1,68 @@
+import { BatchFacilitatorClient } from '@circle-fin/x402-batching/server'
+import type { SettlementResult } from './types.js'
+import { CrumbError } from './errors.js'
+
+let defaultFacilitator: BatchFacilitatorClient | null = null
+
+function getFacilitator(facilitatorUrl?: string): BatchFacilitatorClient {
+  if (facilitatorUrl) {
+    return new BatchFacilitatorClient({ url: facilitatorUrl })
+  }
+  if (!defaultFacilitator) {
+    defaultFacilitator = new BatchFacilitatorClient()
+  }
+  return defaultFacilitator
+}
+
+export async function verifyPayment(
+  payload: any,
+  requirements: any,
+  facilitatorUrl?: string,
+): Promise<{ isValid: boolean; invalidReason?: string; payer?: string }> {
+  const facilitator = getFacilitator(facilitatorUrl)
+  const result = await facilitator.verify(payload, requirements)
+
+  if (!result.isValid) {
+    throw new CrumbError('VERIFY_FAILED', {
+      reason: result.invalidReason,
+    })
+  }
+
+  return result
+}
+
+export async function settlePayment(
+  payload: any,
+  requirements: any,
+  facilitatorUrl?: string,
+): Promise<SettlementResult> {
+  const facilitator = getFacilitator(facilitatorUrl)
+  const result = await facilitator.settle(payload, requirements)
+
+  if (!result.success) {
+    throw new CrumbError('SETTLE_FAILED', {
+      errorReason: result.errorReason,
+    })
+  }
+
+  return {
+    success: true,
+    txHash: result.transaction,
+    amount: requirements.amount ?? '0',
+    formattedAmount: requirements.amount ?? '0',
+    network: result.network,
+    payer: result.payer,
+    timestamp: new Date().toISOString(),
+  }
+}
+
+export async function verifyAndSettle(
+  payload: any,
+  requirements: any,
+  facilitatorUrl?: string,
+): Promise<SettlementResult> {
+  await verifyPayment(payload, requirements, facilitatorUrl)
+  return settlePayment(payload, requirements, facilitatorUrl)
+}
+
+export { BatchFacilitatorClient }

package/src/signing.ts

@@ -0,0 +1,4 @@
+// Signing is handled internally by GatewayClient via BatchEvmScheme.
+// This module re-exports the registration helper for advanced use cases.
+
+export { registerBatchScheme, BatchEvmScheme } from '@circle-fin/x402-batching/client'

package/src/types.ts

@@ -0,0 +1,48 @@
+import type { SupportedChainName, Balances, PayResult } from '@circle-fin/x402-batching/client'
+
+export type { SupportedChainName, Balances, PayResult }
+
+export interface CrumbWallet {
+  address: string
+  privateKey: string
+}
+
+export interface SettlementResult {
+  success: boolean
+  txHash: string
+  amount: string
+  formattedAmount: string
+  network: string
+  payer?: string
+  timestamp: string
+}
+
+export interface FetchOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE'
+  body?: unknown
+  headers?: Record<string, string>
+  maxPayment?: number // USDC ceiling — throws if quoted price exceeds this
+  metadata?: Record<string, string>
+}
+
+export interface FetchResult<T = unknown> {
+  data: T
+  amount: bigint
+  formattedAmount: string
+  txHash: string
+  status: number
+}
+
+export interface MiddlewareConfig {
+  sellerAddress: string
+  networks?: string | string[]
+  facilitatorUrl?: string
+  description?: string
+  onPayment?: (payment: {
+    verified: boolean
+    payer: string
+    amount: string
+    network: string
+    transaction?: string
+  }) => void
+}

package/src/wallet.ts

@@ -0,0 +1,24 @@
+import { privateKeyToAccount, generatePrivateKey } from 'viem/accounts'
+import type { CrumbWallet } from './types.js'
+
+export function createWallet(): CrumbWallet {
+  const privateKey = generatePrivateKey()
+  const account = privateKeyToAccount(privateKey)
+  return {
+    address: account.address,
+    privateKey,
+  }
+}
+
+export function walletFromPrivateKey(privateKey: string): CrumbWallet {
+  const account = privateKeyToAccount(privateKey as `0x${string}`)
+  return {
+    address: account.address,
+    privateKey,
+  }
+}
+
+export function deriveAddress(privateKey: string): string {
+  const account = privateKeyToAccount(privateKey as `0x${string}`)
+  return account.address
+}

package/test/balance.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect, vi } from 'vitest'
+
+const mockGetBalances = vi.fn()
+
+class MockGatewayClient {
+  getBalances = mockGetBalances
+  constructor(public config: any) {}
+}
+
+vi.mock('@circle-fin/x402-batching/client', () => ({
+  GatewayClient: MockGatewayClient,
+}))
+
+const { getBalances, getBalancesForAddress } = await import('../src/balance.js')
+
+describe('getBalances', () => {
+  it('creates a GatewayClient and calls getBalances', async () => {
+    const mockResult = {
+      wallet: { formatted: '10.00' },
+      gateway: { formattedAvailable: '5.00' },
+    }
+    mockGetBalances.mockResolvedValue(mockResult)
+
+    const wallet = { address: '0xabc', privateKey: '0x1234' }
+    const result = await getBalances(wallet)
+    expect(result).toEqual(mockResult)
+    expect(mockGetBalances).toHaveBeenCalled()
+  })
+
+  it('uses baseSepolia as default chain', async () => {
+    mockGetBalances.mockResolvedValue({})
+
+    const wallet = { address: '0xabc', privateKey: '0x1234' }
+    await getBalances(wallet)
+
+    expect(mockGetBalances).toHaveBeenCalled()
+  })
+})
+
+describe('getBalancesForAddress', () => {
+  it('passes address to getBalances call', async () => {
+    mockGetBalances.mockResolvedValue({})
+
+    const wallet = { address: '0xabc', privateKey: '0x1234' }
+    await getBalancesForAddress(wallet, '0xother')
+
+    expect(mockGetBalances).toHaveBeenCalledWith('0xother')
+  })
+})

package/test/errors.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest'
+import { CrumbError } from '../src/errors.js'
+
+describe('CrumbError', () => {
+  it('creates an error with code and detail', () => {
+    const err = new CrumbError('PRICE_EXCEEDED', { quoted: 0.5, ceiling: 0.01 })
+    expect(err).toBeInstanceOf(Error)
+    expect(err).toBeInstanceOf(CrumbError)
+    expect(err.code).toBe('PRICE_EXCEEDED')
+    expect(err.detail).toEqual({ quoted: 0.5, ceiling: 0.01 })
+    expect(err.name).toBe('CrumbError')
+  })
+
+  it('includes code in message', () => {
+    const err = new CrumbError('INSUFFICIENT_BALANCE')
+    expect(err.message).toContain('INSUFFICIENT_BALANCE')
+  })
+
+  it('includes detail in message as JSON', () => {
+    const err = new CrumbError('VERIFY_FAILED', { reason: 'expired' })
+    expect(err.message).toContain('expired')
+  })
+
+  it('works without detail', () => {
+    const err = new CrumbError('NETWORK_ERROR')
+    expect(err.code).toBe('NETWORK_ERROR')
+    expect(err.detail).toBeUndefined()
+    expect(err.message).toContain('NETWORK_ERROR')
+  })
+
+  it('can be caught as Error', () => {
+    try {
+      throw new CrumbError('WALLET_NOT_FOUND')
+    } catch (e) {
+      expect(e).toBeInstanceOf(Error)
+      expect((e as CrumbError).code).toBe('WALLET_NOT_FOUND')
+    }
+  })
+
+  it('preserves all error code types', () => {
+    const codes = [
+      'PRICE_EXCEEDED',
+      'INSUFFICIENT_BALANCE',
+      'VERIFY_FAILED',
+      'SETTLE_FAILED',
+      'INVALID_402',
+      'NOT_402',
+      'PAYMENT_REJECTED',
+      'WALLET_NOT_FOUND',
+      'NETWORK_ERROR',
+    ] as const
+
+    for (const code of codes) {
+      const err = new CrumbError(code)
+      expect(err.code).toBe(code)
+    }
+  })
+})

package/test/payment402.test.ts

@@ -0,0 +1,43 @@
+import { describe, it, expect } from 'vitest'
+import { checkPriceCeiling } from '../src/payment402.js'
+import { CrumbError } from '../src/errors.js'
+
+describe('checkPriceCeiling', () => {
+  it('does not throw when price is under ceiling', () => {
+    expect(() => checkPriceCeiling('0.001', 0.01)).not.toThrow()
+  })
+
+  it('does not throw when price equals ceiling', () => {
+    expect(() => checkPriceCeiling('0.01', 0.01)).not.toThrow()
+  })
+
+  it('throws PRICE_EXCEEDED when price exceeds ceiling', () => {
+    expect(() => checkPriceCeiling('0.05', 0.01)).toThrow(CrumbError)
+    try {
+      checkPriceCeiling('0.05', 0.01)
+    } catch (e) {
+      expect((e as CrumbError).code).toBe('PRICE_EXCEEDED')
+      expect((e as CrumbError).detail).toEqual({ quoted: 0.05, ceiling: 0.01 })
+    }
+  })
+
+  it('handles $ prefix in amount', () => {
+    expect(() => checkPriceCeiling('$0.001', 0.01)).not.toThrow()
+    expect(() => checkPriceCeiling('$0.05', 0.01)).toThrow(CrumbError)
+  })
+
+  it('does not throw for non-numeric amounts', () => {
+    expect(() => checkPriceCeiling('free', 0.01)).not.toThrow()
+    expect(() => checkPriceCeiling('', 0.01)).not.toThrow()
+  })
+
+  it('handles large amounts correctly', () => {
+    expect(() => checkPriceCeiling('100.00', 50)).toThrow(CrumbError)
+    expect(() => checkPriceCeiling('50.00', 100)).not.toThrow()
+  })
+
+  it('handles very small amounts', () => {
+    expect(() => checkPriceCeiling('0.0001', 0.001)).not.toThrow()
+    expect(() => checkPriceCeiling('0.001', 0.0001)).toThrow(CrumbError)
+  })
+})

package/test/settlement.test.ts

@@ -0,0 +1,108 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { CrumbError } from '../src/errors.js'
+
+const mockVerify = vi.fn()
+const mockSettle = vi.fn()
+
+class MockBatchFacilitatorClient {
+  verify = mockVerify
+  settle = mockSettle
+  constructor(_config?: any) {}
+}
+
+vi.mock('@circle-fin/x402-batching/server', () => ({
+  BatchFacilitatorClient: MockBatchFacilitatorClient,
+}))
+
+// Import after mocking
+const { verifyPayment, settlePayment, verifyAndSettle } = await import('../src/settlement.js')
+
+describe('verifyPayment', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('returns result when verification succeeds', async () => {
+    mockVerify.mockResolvedValue({ isValid: true, payer: '0xabc' })
+
+    const result = await verifyPayment({ payment: 'data' }, { amount: '0.01' })
+    expect(result.isValid).toBe(true)
+    expect(result.payer).toBe('0xabc')
+    expect(mockVerify).toHaveBeenCalledWith({ payment: 'data' }, { amount: '0.01' })
+  })
+
+  it('throws VERIFY_FAILED when verification fails', async () => {
+    mockVerify.mockResolvedValue({ isValid: false, invalidReason: 'expired signature' })
+
+    await expect(verifyPayment({}, {})).rejects.toThrow(CrumbError)
+    try {
+      await verifyPayment({}, {})
+    } catch (e) {
+      expect((e as CrumbError).code).toBe('VERIFY_FAILED')
+      expect((e as CrumbError).detail?.reason).toBe('expired signature')
+    }
+  })
+})
+
+describe('settlePayment', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('returns SettlementResult on success', async () => {
+    mockSettle.mockResolvedValue({
+      success: true,
+      transaction: '0xtxhash',
+      network: 'arcTestnet',
+      payer: '0xpayer',
+    })
+
+    const result = await settlePayment({}, { amount: '0.001' })
+    expect(result.success).toBe(true)
+    expect(result.txHash).toBe('0xtxhash')
+    expect(result.network).toBe('arcTestnet')
+    expect(result.payer).toBe('0xpayer')
+    expect(result.amount).toBe('0.001')
+    expect(result.timestamp).toBeDefined()
+  })
+
+  it('throws SETTLE_FAILED when settlement fails', async () => {
+    mockSettle.mockResolvedValue({ success: false, errorReason: 'insufficient funds' })
+
+    await expect(settlePayment({}, {})).rejects.toThrow(CrumbError)
+    try {
+      await settlePayment({}, {})
+    } catch (e) {
+      expect((e as CrumbError).code).toBe('SETTLE_FAILED')
+      expect((e as CrumbError).detail?.errorReason).toBe('insufficient funds')
+    }
+  })
+})
+
+describe('verifyAndSettle', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('calls verify then settle', async () => {
+    mockVerify.mockResolvedValue({ isValid: true, payer: '0xabc' })
+    mockSettle.mockResolvedValue({
+      success: true,
+      transaction: '0xtx',
+      network: 'arcTestnet',
+      payer: '0xabc',
+    })
+
+    const result = await verifyAndSettle({}, { amount: '0.01' })
+    expect(mockVerify).toHaveBeenCalled()
+    expect(mockSettle).toHaveBeenCalled()
+    expect(result.success).toBe(true)
+  })
+
+  it('does not settle if verify fails', async () => {
+    mockVerify.mockResolvedValue({ isValid: false, invalidReason: 'bad sig' })
+
+    await expect(verifyAndSettle({}, {})).rejects.toThrow(CrumbError)
+    expect(mockSettle).not.toHaveBeenCalled()
+  })
+})

package/test/wallet.test.ts

@@ -0,0 +1,58 @@
+import { describe, it, expect } from 'vitest'
+import { createWallet, walletFromPrivateKey, deriveAddress } from '../src/wallet.js'
+
+describe('createWallet', () => {
+  it('returns an object with address and privateKey', () => {
+    const wallet = createWallet()
+    expect(wallet).toHaveProperty('address')
+    expect(wallet).toHaveProperty('privateKey')
+  })
+
+  it('generates a valid hex private key', () => {
+    const wallet = createWallet()
+    expect(wallet.privateKey).toMatch(/^0x[0-9a-f]{64}$/i)
+  })
+
+  it('generates a valid checksummed address', () => {
+    const wallet = createWallet()
+    expect(wallet.address).toMatch(/^0x[0-9a-fA-F]{40}$/)
+  })
+
+  it('generates unique wallets each time', () => {
+    const a = createWallet()
+    const b = createWallet()
+    expect(a.privateKey).not.toBe(b.privateKey)
+    expect(a.address).not.toBe(b.address)
+  })
+})
+
+describe('walletFromPrivateKey', () => {
+  it('derives the correct address from a known private key', () => {
+    const pk = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80'
+    const wallet = walletFromPrivateKey(pk)
+    expect(wallet.privateKey).toBe(pk)
+    // This is the well-known Hardhat account #0 address
+    expect(wallet.address).toBe('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266')
+  })
+
+  it('returns consistent results for the same key', () => {
+    const pk = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80'
+    const a = walletFromPrivateKey(pk)
+    const b = walletFromPrivateKey(pk)
+    expect(a.address).toBe(b.address)
+  })
+})
+
+describe('deriveAddress', () => {
+  it('derives address from a private key', () => {
+    const pk = '0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80'
+    const address = deriveAddress(pk)
+    expect(address).toBe('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266')
+  })
+
+  it('matches createWallet output', () => {
+    const wallet = createWallet()
+    const address = deriveAddress(wallet.privateKey)
+    expect(address).toBe(wallet.address)
+  })
+})

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}