@azeth/sdk 0.2.0

package/dist/payments/agreements.js

@@ -0,0 +1,337 @@
+import { keccak256, toBytes, encodeFunctionData, } from 'viem';
+import { PaymentAgreementModuleAbi } from '@azeth/common/abis';
+import { AzethError } from '@azeth/common';
+import { requireAddress } from '../utils/addresses.js';
+import { wrapContractError } from '../utils/errors.js';
+import { withRetry } from '../utils/retry.js';
+// AgreementCreated(address indexed account, uint256 indexed agreementId, address indexed payee, address token, uint256 amount, uint256 interval, uint256 endTime)
+const AGREEMENT_CREATED_TOPIC = keccak256(toBytes('AgreementCreated(address,uint256,address,address,uint256,uint256,uint256)'));
+/** Create a recurring payment agreement via ERC-4337 UserOperation.
+ *
+ *  Routes the call through the smart account so msg.sender = smart account address.
+ *  The SmartAccountClient wraps the PaymentAgreementModule.createAgreement() call
+ *  inside AzethAccount.execute() via a UserOp submitted to EntryPoint v0.7.
+ */
+export async function createPaymentAgreement(publicClient, smartAccountClient, addresses, account, params) {
+    if (!/^0x[a-fA-F0-9]{40}$/.test(params.payee)) {
+        throw new AzethError('Invalid payee address format', 'INVALID_INPUT', { field: 'payee' });
+    }
+    if (!/^0x[a-fA-F0-9]{40}$/.test(params.token)) {
+        throw new AzethError('Invalid token address format', 'INVALID_INPUT', { field: 'token' });
+    }
+    if (params.amount <= 0n) {
+        throw new AzethError('Payment amount must be positive', 'INVALID_INPUT', { field: 'amount' });
+    }
+    if (!Number.isInteger(params.interval) || params.interval < 1) {
+        throw new AzethError('Interval must be a positive integer (seconds)', 'INVALID_INPUT', { field: 'interval' });
+    }
+    const moduleAddress = requireAddress(addresses, 'paymentAgreementModule');
+    let txHash;
+    try {
+        const data = encodeFunctionData({
+            abi: PaymentAgreementModuleAbi,
+            functionName: 'createAgreement',
+            args: [
+                params.payee,
+                params.token,
+                params.amount,
+                BigInt(params.interval),
+                params.endTime ?? 0n,
+                BigInt(params.maxExecutions ?? 0),
+                params.totalCap ?? (params.maxExecutions ? params.amount * BigInt(params.maxExecutions) : params.amount * 365n),
+            ],
+        });
+        txHash = await smartAccountClient.sendTransaction({
+            to: moduleAddress,
+            value: 0n,
+            data,
+        });
+    }
+    catch (err) {
+        throw wrapContractError(err, 'PAYMENT_FAILED');
+    }
+    const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash, timeout: 120_000 });
+    if (receipt.status === 'reverted') {
+        throw new AzethError('Transaction reverted', 'CONTRACT_ERROR', { txHash });
+    }
+    // Parse AgreementCreated event for agreementId — filter by module address and event signature
+    let agreementId = 0n;
+    for (const log of receipt.logs) {
+        if (log.address?.toLowerCase() === moduleAddress.toLowerCase() && log.topics[0] === AGREEMENT_CREATED_TOPIC && log.topics.length >= 3) {
+            agreementId = BigInt(log.topics[2] ?? '0x0');
+            break;
+        }
+    }
+    return { agreementId, txHash };
+}
+/** Get agreement details */
+export async function getAgreement(publicClient, addresses, account, agreementId) {
+    const moduleAddress = requireAddress(addresses, 'paymentAgreementModule');
+    const result = await withRetry(() => publicClient.readContract({
+        address: moduleAddress,
+        abi: PaymentAgreementModuleAbi,
+        functionName: 'getAgreement',
+        args: [account, agreementId],
+    }));
+    return {
+        id: agreementId,
+        payee: result.payee,
+        token: result.token,
+        amount: result.amount,
+        interval: result.interval,
+        endTime: result.endTime,
+        lastExecuted: result.lastExecuted,
+        maxExecutions: result.maxExecutions,
+        executionCount: result.executionCount,
+        totalCap: result.totalCap,
+        totalPaid: result.totalPaid,
+        active: result.active,
+    };
+}
+/** Audit #13 M-14 fix: Cap the number of agreements scanned to prevent RPC flooding */
+const MAX_AGREEMENT_SCAN = 100;
+/** Find an active agreement from a given account to a specific payee.
+ *  Iterates from newest to oldest (newest more likely active).
+ *  Scans at most MAX_AGREEMENT_SCAN agreements to prevent O(n) RPC calls.
+ *
+ *  @param publicClient - viem public client for on-chain reads
+ *  @param addresses - Contract addresses containing paymentAgreementModule
+ *  @param account - The payer's smart account address
+ *  @param payee - The payee address to match
+ *  @param token - Optional token address to filter by
+ *  @returns The first matching active agreement, or null
+ */
+export async function findAgreementWithPayee(publicClient, addresses, account, payee, token) {
+    const moduleAddress = requireAddress(addresses, 'paymentAgreementModule');
+    // Get agreement count
+    let count;
+    try {
+        count = await withRetry(() => publicClient.readContract({
+            address: moduleAddress,
+            abi: PaymentAgreementModuleAbi,
+            functionName: 'getAgreementCount',
+            args: [account],
+        }));
+    }
+    catch {
+        return null;
+    }
+    if (count === 0n)
+        return null;
+    const now = BigInt(Math.floor(Date.now() / 1000));
+    // Cap scan to most recent MAX_AGREEMENT_SCAN agreements to prevent RPC flooding
+    const scanLimit = count < BigInt(MAX_AGREEMENT_SCAN) ? count : BigInt(MAX_AGREEMENT_SCAN);
+    const startIndex = count - 1n;
+    const endIndex = count - scanLimit;
+    // Iterate from newest to oldest (most recent agreements are most likely active)
+    for (let i = startIndex; i >= endIndex; i--) {
+        let agreement;
+        try {
+            agreement = await getAgreement(publicClient, addresses, account, i);
+        }
+        catch {
+            continue;
+        }
+        if (!agreement.active)
+            continue;
+        if (agreement.payee.toLowerCase() !== payee.toLowerCase())
+            continue;
+        if (token && agreement.token.toLowerCase() !== token.toLowerCase())
+            continue;
+        if (agreement.endTime !== 0n && agreement.endTime <= now)
+            continue;
+        if (agreement.maxExecutions !== 0n && agreement.executionCount >= agreement.maxExecutions)
+            continue;
+        return agreement;
+    }
+    return null;
+}
+/** Execute a due payment agreement via ERC-4337 UserOperation.
+ *
+ *  Routes the call through the smart account so msg.sender = smart account address.
+ */
+export async function executeAgreement(publicClient, smartAccountClient, addresses, account, agreementId) {
+    const moduleAddress = requireAddress(addresses, 'paymentAgreementModule');
+    let txHash;
+    try {
+        const data = encodeFunctionData({
+            abi: PaymentAgreementModuleAbi,
+            functionName: 'executeAgreement',
+            args: [account, agreementId],
+        });
+        txHash = await smartAccountClient.sendTransaction({
+            to: moduleAddress,
+            value: 0n,
+            data,
+        });
+    }
+    catch (err) {
+        if (err instanceof AzethError)
+            throw err;
+        throw new AzethError(err instanceof Error ? err.message : 'Failed to execute agreement', 'PAYMENT_FAILED', { operation: 'agreement_execution', originalError: err instanceof Error ? err.name : undefined });
+    }
+    const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash, timeout: 120_000 });
+    if (receipt.status === 'reverted') {
+        throw new AzethError('Transaction reverted', 'CONTRACT_ERROR', { txHash });
+    }
+    return txHash;
+}
+/** Execute a payment agreement as a third-party keeper.
+ *
+ *  The contract's executeAgreement() is permissionless — any msg.sender can trigger it.
+ *  When the caller is NOT the payer (i.e., it's a keeper or payee), we cannot build a
+ *  UserOp for the payer's smart account (AA24 signature mismatch). Instead:
+ *
+ *  - If the keeper has their own smart account: route via the keeper's SmartAccountClient
+ *    (the keeper's smart account calls the module, which executes on the payer's account)
+ *  - If the keeper has no smart account: call the module directly from the keeper's EOA
+ *    via walletClient.writeContract()
+ */
+export async function executeAgreementAsKeeper(publicClient, keeperSmartAccountClient, walletClient, addresses, payerAccount, agreementId) {
+    const moduleAddress = requireAddress(addresses, 'paymentAgreementModule');
+    let txHash;
+    try {
+        const data = encodeFunctionData({
+            abi: PaymentAgreementModuleAbi,
+            functionName: 'executeAgreement',
+            args: [payerAccount, agreementId],
+        });
+        if (keeperSmartAccountClient) {
+            // Route via keeper's own smart account (UserOp from keeper's account)
+            txHash = await keeperSmartAccountClient.sendTransaction({
+                to: moduleAddress,
+                value: 0n,
+                data,
+            });
+        }
+        else {
+            // Direct EOA call — keeper has no smart account
+            txHash = await walletClient.writeContract({
+                address: moduleAddress,
+                abi: PaymentAgreementModuleAbi,
+                functionName: 'executeAgreement',
+                args: [payerAccount, agreementId],
+            });
+        }
+    }
+    catch (err) {
+        if (err instanceof AzethError)
+            throw err;
+        throw new AzethError(err instanceof Error ? err.message : 'Failed to execute agreement as keeper', 'PAYMENT_FAILED', { operation: 'agreement_execution', originalError: err instanceof Error ? err.name : undefined });
+    }
+    const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash, timeout: 120_000 });
+    if (receipt.status === 'reverted') {
+        throw new AzethError('Transaction reverted', 'CONTRACT_ERROR', { txHash });
+    }
+    return txHash;
+}
+/** Cancel an active payment agreement via ERC-4337 UserOperation.
+ *
+ *  Routes the call through the smart account so msg.sender = smart account address.
+ *  Only the payer (agreement creator) can cancel. Immediate effect, no timelock.
+ */
+export async function cancelAgreement(publicClient, smartAccountClient, addresses, agreementId) {
+    const moduleAddress = requireAddress(addresses, 'paymentAgreementModule');
+    let txHash;
+    try {
+        const data = encodeFunctionData({
+            abi: PaymentAgreementModuleAbi,
+            functionName: 'cancelAgreement',
+            args: [agreementId],
+        });
+        txHash = await smartAccountClient.sendTransaction({
+            to: moduleAddress,
+            value: 0n,
+            data,
+        });
+    }
+    catch (err) {
+        if (err instanceof AzethError)
+            throw err;
+        throw new AzethError(err instanceof Error ? err.message : 'Failed to cancel agreement', 'PAYMENT_FAILED', { operation: 'agreement_cancel', originalError: err instanceof Error ? err.name : undefined });
+    }
+    const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash, timeout: 120_000 });
+    if (receipt.status === 'reverted') {
+        throw new AzethError('Transaction reverted', 'CONTRACT_ERROR', { txHash });
+    }
+    return txHash;
+}
+/** Get the total number of agreements for an account */
+export async function getAgreementCount(publicClient, addresses, account) {
+    const moduleAddress = requireAddress(addresses, 'paymentAgreementModule');
+    return await withRetry(() => publicClient.readContract({
+        address: moduleAddress,
+        abi: PaymentAgreementModuleAbi,
+        functionName: 'getAgreementCount',
+        args: [account],
+    }));
+}
+/** Check if a payment agreement can be executed right now.
+ *  Returns [executable, reason] — reason explains why if not executable.
+ */
+export async function canExecutePayment(publicClient, addresses, account, agreementId) {
+    const moduleAddress = requireAddress(addresses, 'paymentAgreementModule');
+    const result = await withRetry(() => publicClient.readContract({
+        address: moduleAddress,
+        abi: PaymentAgreementModuleAbi,
+        functionName: 'canExecutePayment',
+        args: [account, agreementId],
+    }));
+    return { executable: result[0], reason: result[1] };
+}
+/** Check if a payment agreement is executable (ignoring interval timing).
+ *  Checks: active, not expired, not maxed, not capped, guardian whitelist,
+ *  guardian limits, and payer balance >= accrued amount. */
+export async function isAgreementExecutable(publicClient, addresses, account, agreementId) {
+    const moduleAddress = requireAddress(addresses, 'paymentAgreementModule');
+    return await withRetry(() => publicClient.readContract({
+        address: moduleAddress,
+        abi: PaymentAgreementModuleAbi,
+        functionName: 'isAgreementExecutable',
+        args: [account, agreementId],
+    }));
+}
+/** Get comprehensive agreement data in a single RPC call.
+ *  Combines getAgreement + isAgreementExecutable + isAgreementDue +
+ *  getNextExecutionTime + getAgreementCount. */
+export async function getAgreementData(publicClient, addresses, account, agreementId) {
+    const moduleAddress = requireAddress(addresses, 'paymentAgreementModule');
+    const result = await withRetry(() => publicClient.readContract({
+        address: moduleAddress,
+        abi: PaymentAgreementModuleAbi,
+        functionName: 'getAgreementData',
+        args: [account, agreementId],
+    }));
+    return {
+        agreement: {
+            id: agreementId,
+            payee: result[0].payee,
+            token: result[0].token,
+            amount: result[0].amount,
+            interval: result[0].interval,
+            endTime: result[0].endTime,
+            lastExecuted: result[0].lastExecuted,
+            maxExecutions: result[0].maxExecutions,
+            executionCount: result[0].executionCount,
+            totalCap: result[0].totalCap,
+            totalPaid: result[0].totalPaid,
+            active: result[0].active,
+        },
+        executable: result[1],
+        reason: result[2],
+        isDue: result[3],
+        nextExecutionTime: result[4],
+        count: result[5],
+    };
+}
+/** Get the next execution timestamp for a payment agreement */
+export async function getNextExecutionTime(publicClient, addresses, account, agreementId) {
+    const moduleAddress = requireAddress(addresses, 'paymentAgreementModule');
+    return await withRetry(() => publicClient.readContract({
+        address: moduleAddress,
+        abi: PaymentAgreementModuleAbi,
+        functionName: 'getNextExecutionTime',
+        args: [account, agreementId],
+    }));
+}
+//# sourceMappingURL=agreements.js.map

package/dist/payments/agreements.js.map

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

package/dist/payments/budget.d.ts

@@ -0,0 +1,118 @@
+/** Reputation-aware budget manager for x402 payments.
+ *
+ *  Provides per-transaction and per-session spending limits that scale
+ *  with the target service's on-chain reputation. Higher reputation =
+ *  higher trust = higher allowed spending.
+ *
+ *  Budget tiers are configurable and layer ON TOP of the Guardian Module's
+ *  on-chain dailySpendLimitUSD (which is the hard ceiling that can't be bypassed).
+ *  This is a client-side soft limit for convenience and safety.
+ */
+/** A single budget tier: reputation threshold → per-transaction limit */
+export interface BudgetTier {
+    /** Minimum reputation score to qualify for this tier (0-100) */
+    minReputation: number;
+    /** Maximum payment per transaction in token smallest unit (e.g., USDC 6 decimals) */
+    maxPerTransaction: bigint;
+    /** Tier label for display/logging */
+    label: string;
+}
+/** Default budget tiers (ordered highest reputation first) */
+export declare const DEFAULT_BUDGET_TIERS: readonly BudgetTier[];
+/** Budget manager configuration */
+export interface BudgetConfig {
+    /** Custom budget tiers (overrides defaults). Must be sorted by minReputation descending. */
+    tiers?: BudgetTier[];
+    /** Maximum spending per session across all services (in token smallest unit).
+     *  Default: 10,000,000 (10 USDC) */
+    maxPerSession?: bigint;
+    /** Whether to enforce budget checks (default: true).
+     *  When false, budget is tracked but not enforced. */
+    enforce?: boolean;
+    /** Fallback per-tx limit when reputation is unknown (default: bronze tier) */
+    unknownReputationLimit?: bigint;
+}
+/** Result of a budget check */
+export interface BudgetCheckResult {
+    allowed: boolean;
+    reason?: string;
+    /** The tier that was matched */
+    tier?: string;
+    /** Maximum allowed for this transaction */
+    maxAllowed?: bigint;
+    /** Remaining session budget */
+    sessionRemaining?: bigint;
+}
+/** Record of a completed payment for budget tracking */
+interface SpendRecord {
+    amount: bigint;
+    service: string;
+    timestamp: number;
+}
+/** Manages spending limits based on service reputation.
+ *
+ *  Usage:
+ *  ```ts
+ *  const budget = new BudgetManager({ maxPerSession: 10_000_000n });
+ *  const check = budget.checkBudget(amount, serviceReputation);
+ *  if (!check.allowed) throw new Error(check.reason);
+ *  // ... make payment ...
+ *  budget.recordSpend(amount, serviceUrl);
+ *  ```
+ */
+export declare class BudgetManager {
+    private static readonly MAX_HISTORY;
+    private readonly _tiers;
+    private readonly _maxPerSession;
+    private readonly _enforce;
+    private readonly _unknownLimit;
+    private _sessionSpent;
+    private _history;
+    /** Promise-based mutex for atomic check-and-spend operations (C-1 fix) */
+    private _lock;
+    constructor(config?: BudgetConfig);
+    /** Acquire exclusive budget access for atomic check-and-spend.
+     *
+     *  Serializes concurrent async operations so that checkBudget + recordSpend
+     *  cannot be interleaved by parallel payment flows (TOCTOU prevention).
+     *
+     *  Audit #10: Timeout prevents permanent deadlock if fn() never resolves.
+     *  120s allows for full smart_pay cycle: discovery + on-chain settlement +
+     *  UserOp bundling + retries + reputation feedback.
+     *
+     *  @param fn - The async function to execute while holding the lock
+     *  @returns The return value of fn
+     */
+    acquireBudgetLock<T>(fn: () => Promise<T>): Promise<T>;
+    /** Check if a payment is within budget.
+     *
+     *  @param amount - Payment amount in token smallest unit
+     *  @param serviceReputation - Service's reputation score (0-100), or undefined if unknown
+     *  @returns Budget check result with allowed/denied and reason
+     */
+    checkBudget(amount: bigint, serviceReputation?: number): BudgetCheckResult;
+    /** Record a completed payment.
+     *
+     *  History is capped at MAX_HISTORY entries (M-1 fix) to prevent unbounded growth.
+     */
+    recordSpend(amount: bigint, service: string): void;
+    /** Get total spent this session */
+    getSessionSpent(): bigint;
+    /** Get remaining session budget */
+    getRemaining(): bigint;
+    /** Get spending history */
+    getHistory(): readonly SpendRecord[];
+    /** Reset session spending (e.g., for a new session) */
+    reset(): void;
+    /** Get the per-transaction limit for a given reputation score */
+    getLimitForReputation(reputation?: number): bigint;
+    private _findTier;
+}
+/** Compute a reputation score (0-100) from on-chain summary data.
+ *
+ *  Converts the raw summaryValue/summaryValueDecimals from the ERC-8004
+ *  Reputation Registry into a 0-100 integer score suitable for budget tier lookup.
+ */
+export declare function reputationToScore(summaryValue: bigint, summaryValueDecimals: number): number;
+export {};
+//# sourceMappingURL=budget.d.ts.map

package/dist/payments/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../../src/payments/budget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,aAAa,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,8DAA8D;AAC9D,eAAO,MAAM,oBAAoB,EAAE,SAAS,UAAU,EAK5C,CAAC;AAEX,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,4FAA4F;IAC5F,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB;wCACoC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;0DACsD;IACtD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,+BAA+B;AAC/B,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+BAA+B;IAC/B,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wDAAwD;AACxD,UAAU,WAAW;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAU;IAE7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,aAAa,CAAM;IAC3B,OAAO,CAAC,QAAQ,CAAqB;IAErC,0EAA0E;IAC1E,OAAO,CAAC,KAAK,CAAoC;gBAErC,MAAM,CAAC,EAAE,YAAY;IAOjC;;;;;;;;;;;OAWG;IACG,iBAAiB,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAwB5D;;;;;OAKG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,GAAG,iBAAiB;IAsC1E;;;OAGG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAQlD,mCAAmC;IACnC,eAAe,IAAI,MAAM;IAIzB,mCAAmC;IACnC,YAAY,IAAI,MAAM;IAKtB,2BAA2B;IAC3B,UAAU,IAAI,SAAS,WAAW,EAAE;IAIpC,uDAAuD;IACvD,KAAK,IAAI,IAAI;IAKb,iEAAiE;IACjE,qBAAqB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM;IAIlD,OAAO,CAAC,SAAS;CAUlB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,oBAAoB,EAAE,MAAM,GAAG,MAAM,CAQ5F"}

package/dist/payments/budget.js

@@ -0,0 +1,176 @@
+/** Reputation-aware budget manager for x402 payments.
+ *
+ *  Provides per-transaction and per-session spending limits that scale
+ *  with the target service's on-chain reputation. Higher reputation =
+ *  higher trust = higher allowed spending.
+ *
+ *  Budget tiers are configurable and layer ON TOP of the Guardian Module's
+ *  on-chain dailySpendLimitUSD (which is the hard ceiling that can't be bypassed).
+ *  This is a client-side soft limit for convenience and safety.
+ */
+import { AzethError } from '@azeth/common';
+/** Default budget tiers (ordered highest reputation first) */
+export const DEFAULT_BUDGET_TIERS = [
+    { minReputation: 90, maxPerTransaction: 5000000n, label: 'diamond' }, // $5.00 USDC
+    { minReputation: 70, maxPerTransaction: 1000000n, label: 'gold' }, // $1.00 USDC
+    { minReputation: 50, maxPerTransaction: 500000n, label: 'silver' }, // $0.50 USDC
+    { minReputation: 0, maxPerTransaction: 100000n, label: 'bronze' }, // $0.10 USDC
+];
+/** Manages spending limits based on service reputation.
+ *
+ *  Usage:
+ *  ```ts
+ *  const budget = new BudgetManager({ maxPerSession: 10_000_000n });
+ *  const check = budget.checkBudget(amount, serviceReputation);
+ *  if (!check.allowed) throw new Error(check.reason);
+ *  // ... make payment ...
+ *  budget.recordSpend(amount, serviceUrl);
+ *  ```
+ */
+export class BudgetManager {
+    static MAX_HISTORY = 10_000;
+    _tiers;
+    _maxPerSession;
+    _enforce;
+    _unknownLimit;
+    _sessionSpent = 0n;
+    _history = [];
+    /** Promise-based mutex for atomic check-and-spend operations (C-1 fix) */
+    _lock = Promise.resolve();
+    constructor(config) {
+        this._tiers = config?.tiers ?? DEFAULT_BUDGET_TIERS;
+        this._maxPerSession = config?.maxPerSession ?? 10000000n;
+        this._enforce = config?.enforce ?? true;
+        this._unknownLimit = config?.unknownReputationLimit ?? 100000n; // $0.10 USDC
+    }
+    /** Acquire exclusive budget access for atomic check-and-spend.
+     *
+     *  Serializes concurrent async operations so that checkBudget + recordSpend
+     *  cannot be interleaved by parallel payment flows (TOCTOU prevention).
+     *
+     *  Audit #10: Timeout prevents permanent deadlock if fn() never resolves.
+     *  120s allows for full smart_pay cycle: discovery + on-chain settlement +
+     *  UserOp bundling + retries + reputation feedback.
+     *
+     *  @param fn - The async function to execute while holding the lock
+     *  @returns The return value of fn
+     */
+    async acquireBudgetLock(fn) {
+        const LOCK_TIMEOUT_MS = 120_000;
+        let release;
+        const next = new Promise(resolve => { release = resolve; });
+        const prev = this._lock;
+        this._lock = next;
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new AzethError('Budget lock timeout', 'NETWORK_ERROR')), LOCK_TIMEOUT_MS);
+        });
+        try {
+            await Promise.race([prev, timeout]);
+            return await Promise.race([fn(), timeout]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+            release();
+        }
+    }
+    /** Check if a payment is within budget.
+     *
+     *  @param amount - Payment amount in token smallest unit
+     *  @param serviceReputation - Service's reputation score (0-100), or undefined if unknown
+     *  @returns Budget check result with allowed/denied and reason
+     */
+    checkBudget(amount, serviceReputation) {
+        const sessionRemaining = this._maxPerSession - this._sessionSpent;
+        // Check session limit
+        if (amount > sessionRemaining) {
+            const result = {
+                allowed: false,
+                reason: `Session budget exceeded: ${amount} requested, ${sessionRemaining} remaining of ${this._maxPerSession} total`,
+                sessionRemaining,
+            };
+            return this._enforce ? result : { ...result, allowed: true };
+        }
+        // Find matching tier
+        const tier = this._findTier(serviceReputation);
+        const maxAllowed = tier?.maxPerTransaction ?? this._unknownLimit;
+        const tierLabel = tier?.label ?? 'unknown';
+        // Check per-transaction limit
+        if (amount > maxAllowed) {
+            const result = {
+                allowed: false,
+                reason: `Amount ${amount} exceeds ${tierLabel} tier limit of ${maxAllowed} (reputation: ${serviceReputation ?? 'unknown'})`,
+                tier: tierLabel,
+                maxAllowed,
+                sessionRemaining,
+            };
+            return this._enforce ? result : { ...result, allowed: true };
+        }
+        return {
+            allowed: true,
+            tier: tierLabel,
+            maxAllowed,
+            sessionRemaining,
+        };
+    }
+    /** Record a completed payment.
+     *
+     *  History is capped at MAX_HISTORY entries (M-1 fix) to prevent unbounded growth.
+     */
+    recordSpend(amount, service) {
+        this._sessionSpent += amount;
+        this._history.push({ amount, service, timestamp: Date.now() });
+        if (this._history.length > BudgetManager.MAX_HISTORY) {
+            this._history = this._history.slice(-BudgetManager.MAX_HISTORY);
+        }
+    }
+    /** Get total spent this session */
+    getSessionSpent() {
+        return this._sessionSpent;
+    }
+    /** Get remaining session budget */
+    getRemaining() {
+        const remaining = this._maxPerSession - this._sessionSpent;
+        return remaining > 0n ? remaining : 0n;
+    }
+    /** Get spending history */
+    getHistory() {
+        return this._history;
+    }
+    /** Reset session spending (e.g., for a new session) */
+    reset() {
+        this._sessionSpent = 0n;
+        this._history = [];
+    }
+    /** Get the per-transaction limit for a given reputation score */
+    getLimitForReputation(reputation) {
+        return this._findTier(reputation)?.maxPerTransaction ?? this._unknownLimit;
+    }
+    _findTier(reputation) {
+        if (reputation === undefined || reputation === null)
+            return undefined;
+        // Tiers are sorted by minReputation descending — first match wins
+        for (const tier of this._tiers) {
+            if (reputation >= tier.minReputation) {
+                return tier;
+            }
+        }
+        return undefined;
+    }
+}
+/** Compute a reputation score (0-100) from on-chain summary data.
+ *
+ *  Converts the raw summaryValue/summaryValueDecimals from the ERC-8004
+ *  Reputation Registry into a 0-100 integer score suitable for budget tier lookup.
+ */
+export function reputationToScore(summaryValue, summaryValueDecimals) {
+    if (summaryValueDecimals === 0) {
+        const val = Number(summaryValue);
+        return Math.max(0, Math.min(100, val));
+    }
+    const divisor = 10n ** BigInt(summaryValueDecimals);
+    const score = Number(summaryValue) / Number(divisor);
+    return Math.max(0, Math.min(100, Math.round(score)));
+}
+//# sourceMappingURL=budget.js.map

package/dist/payments/budget.js.map

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