@sovrx402/agent-sdk 1.0.0

package/dist/BaseAgent.d.ts

@@ -0,0 +1,25 @@
+/**
+ * SOVRx402 BaseAgent — Base 主网 Agent（x402 协议）
+ *
+ * call() 流程：
+ *   GET /resource → 200 → 返回
+ *   GET /resource → 402 → 读 PAYMENT-REQUIRED → 签 EIP-3009 → 带 X-PAYMENT 重试一次
+ *   重试仍 402 → PaymentRejectedError
+ */
+import { ethers } from 'ethers';
+import type { BaseAgentConfig, SetupResult, CallResult, AgentStatus } from './types';
+export declare class BaseAgent {
+    protected readonly config: BaseAgentConfig;
+    protected readonly wallet: ethers.Wallet;
+    protected readonly provider: ethers.JsonRpcProvider;
+    protected readonly usdc: ethers.Contract;
+    protected usdcName: string;
+    protected usdcVersion: string;
+    protected chainId: number;
+    protected initialized: boolean;
+    constructor(config: BaseAgentConfig);
+    setup(): Promise<SetupResult>;
+    call(resource: string): Promise<CallResult>;
+    getStatus(): Promise<AgentStatus>;
+    protected signEip3009(payTo: string, value: bigint): Promise<Record<string, unknown>>;
+}

package/dist/BaseAgent.js

@@ -0,0 +1,164 @@
+"use strict";
+/**
+ * SOVRx402 BaseAgent — Base 主网 Agent（x402 协议）
+ *
+ * call() 流程：
+ *   GET /resource → 200 → 返回
+ *   GET /resource → 402 → 读 PAYMENT-REQUIRED → 签 EIP-3009 → 带 X-PAYMENT 重试一次
+ *   重试仍 402 → PaymentRejectedError
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseAgent = void 0;
+const ethers_1 = require("ethers");
+const errors_1 = require("./errors");
+const USDC_ABI = [
+    'function name() view returns (string)',
+    'function version() view returns (string)',
+    'function decimals() view returns (uint8)',
+    'function balanceOf(address) view returns (uint256)',
+];
+const EIP3009_TYPES = {
+    TransferWithAuthorization: [
+        { name: 'from', type: 'address' },
+        { name: 'to', type: 'address' },
+        { name: 'value', type: 'uint256' },
+        { name: 'validAfter', type: 'uint256' },
+        { name: 'validBefore', type: 'uint256' },
+        { name: 'nonce', type: 'bytes32' },
+    ],
+};
+class BaseAgent {
+    constructor(config) {
+        this.config = config;
+        // EIP-3009 domain info — 在 setup() 中读取，测试可通过子类覆盖
+        this.usdcName = '';
+        this.usdcVersion = '2';
+        this.chainId = 8453;
+        this.initialized = false;
+        const rpc = config.rpcUrl ?? 'https://mainnet.base.org';
+        this.provider = new ethers_1.ethers.JsonRpcProvider(rpc);
+        this.wallet = new ethers_1.ethers.Wallet(config.privateKey, this.provider);
+        this.usdc = new ethers_1.ethers.Contract(config.usdcAddress, USDC_ABI, this.provider);
+    }
+    async setup() {
+        if (!ethers_1.ethers.isAddress(this.config.usdcAddress)) {
+            throw new errors_1.InvalidAddressError(this.config.usdcAddress);
+        }
+        const network = await this.provider.getNetwork();
+        this.chainId = Number(network.chainId);
+        const [name, version, nativeBal, usdcBal] = await Promise.all([
+            this.usdc.name(),
+            this.usdc.version(),
+            this.provider.getBalance(this.wallet.address),
+            this.usdc.balanceOf(this.wallet.address),
+        ]);
+        this.usdcName = name;
+        this.usdcVersion = version;
+        this.initialized = true;
+        return {
+            address: this.wallet.address,
+            chainId: this.chainId,
+            nativeBalance: nativeBal,
+            usdcBalance: usdcBal,
+        };
+    }
+    async call(resource) {
+        const path = resource.startsWith('/') ? resource : '/' + resource;
+        const url = this.config.gatewayUrl.replace(/\/$/, '') + path;
+        // ── 第一次请求 ────────────────────────────────────────────────────────
+        let resp;
+        try {
+            resp = await fetch(url);
+        }
+        catch (e) {
+            throw new errors_1.NetworkError(url, undefined, e);
+        }
+        if (resp.ok) {
+            return { success: true, data: await resp.json() };
+        }
+        if (resp.status !== 402) {
+            throw new errors_1.GatewayError(resp.status, await resp.json().catch(() => null));
+        }
+        // ── 402：读取 PAYMENT-REQUIRED ────────────────────────────────────────
+        const payHeader = resp.headers.get('PAYMENT-REQUIRED') ??
+            resp.headers.get('X-PAYMENT-REQUIRED');
+        if (!payHeader) {
+            throw new errors_1.PaymentRejectedError('NO_PAYMENT_HEADER', 'PAYMENT-REQUIRED header missing');
+        }
+        let payReq;
+        try {
+            payReq = JSON.parse(payHeader);
+        }
+        catch {
+            throw new errors_1.PaymentRejectedError('INVALID_PAYMENT_HEADER', 'Cannot parse PAYMENT-REQUIRED');
+        }
+        const payTo = payReq.payTo ?? '';
+        const amount = BigInt(payReq.maxAmountRequired ?? '0');
+        // ── 签 EIP-3009 ───────────────────────────────────────────────────────
+        const paymentPayload = await this.signEip3009(payTo, amount);
+        // ── 带 X-PAYMENT 重试 ──────────────────────────────────────────────────
+        try {
+            resp = await fetch(url, {
+                headers: { 'X-PAYMENT': JSON.stringify(paymentPayload) },
+            });
+        }
+        catch (e) {
+            throw new errors_1.NetworkError(url, undefined, e);
+        }
+        if (resp.ok) {
+            return { success: true, data: await resp.json() };
+        }
+        if (resp.status === 402) {
+            throw new errors_1.PaymentRejectedError('PAYMENT_REJECTED', 'Gateway rejected payment on retry');
+        }
+        throw new errors_1.GatewayError(resp.status, await resp.json().catch(() => null));
+    }
+    async getStatus() {
+        const [nativeBal, usdcBal] = await Promise.all([
+            this.provider.getBalance(this.wallet.address),
+            this.usdc.balanceOf(this.wallet.address),
+        ]);
+        return {
+            address: this.wallet.address,
+            chainId: this.chainId,
+            nativeBalance: nativeBal,
+            usdcBalance: usdcBal,
+        };
+    }
+    // ── 内部：EIP-3009 签名 ───────────────────────────────────────────────────
+    async signEip3009(payTo, value) {
+        const nonce = ethers_1.ethers.hexlify(ethers_1.ethers.randomBytes(32));
+        const validBefore = BigInt(Math.floor(Date.now() / 1000) + 300);
+        const domain = {
+            name: this.usdcName,
+            version: this.usdcVersion,
+            chainId: this.chainId,
+            verifyingContract: this.config.usdcAddress,
+        };
+        const message = {
+            from: this.wallet.address,
+            to: payTo,
+            value,
+            validAfter: 0n,
+            validBefore,
+            nonce,
+        };
+        const signature = await this.wallet.signTypedData(domain, EIP3009_TYPES, message);
+        return {
+            scheme: 'exact',
+            networkId: `eip155:${this.chainId}`,
+            payload: {
+                authorization: {
+                    from: this.wallet.address,
+                    to: payTo,
+                    value: value.toString(),
+                    validAfter: '0',
+                    validBefore: validBefore.toString(),
+                    nonce,
+                },
+                signature,
+            },
+        };
+    }
+}
+exports.BaseAgent = BaseAgent;

package/dist/BscAgent.d.ts

@@ -0,0 +1,36 @@
+/**
+ * SOVRx402 BscAgent — BSC 主网 Agent（EIP-712 Auth）
+ *
+ * call() 流程：
+ *   生成 EIP-712 PaymentAuth → X-SOVRx402-Signature → 200 → 返回
+ *   401 AUTH_EXPIRED / NONCE_REUSED / PRICE_MISMATCH → 重签 → 重试一次
+ *   401 SIGNER_MISMATCH / PATH_MISMATCH / CHAIN_MISMATCH → 直接抛错
+ *   402 → ApprovalRequiredError
+ *   403 → NotRegisteredError
+ */
+import { ethers } from 'ethers';
+import type { BscAgentConfig, SetupResult, RegisterResult, ApproveResult, CallResult, SettleResult, AgentStatus } from './types';
+export declare class BscAgent {
+    protected readonly config: BscAgentConfig;
+    protected readonly wallet: ethers.Wallet;
+    protected readonly provider: ethers.JsonRpcProvider;
+    protected readonly registry: ethers.Contract;
+    protected readonly ledger: ethers.Contract;
+    protected readonly usdc: ethers.Contract;
+    protected operatorAddress: string;
+    protected depositAmount: bigint;
+    protected pricePerCall: bigint;
+    protected initialized: boolean;
+    constructor(config: BscAgentConfig);
+    setup(): Promise<SetupResult>;
+    register(): Promise<RegisterResult>;
+    approveRegistry(amount: bigint): Promise<ApproveResult>;
+    approveOperator(amount: bigint): Promise<ApproveResult>;
+    approveLedger(amount: bigint): Promise<ApproveResult>;
+    private _approve;
+    call(resource: string): Promise<CallResult>;
+    settle(): Promise<SettleResult>;
+    getStatus(): Promise<AgentStatus>;
+    private signPaymentAuth;
+    protected fetchPriceFromGateway(): Promise<bigint>;
+}

package/dist/BscAgent.js

@@ -0,0 +1,358 @@
+"use strict";
+/**
+ * SOVRx402 BscAgent — BSC 主网 Agent（EIP-712 Auth）
+ *
+ * call() 流程：
+ *   生成 EIP-712 PaymentAuth → X-SOVRx402-Signature → 200 → 返回
+ *   401 AUTH_EXPIRED / NONCE_REUSED / PRICE_MISMATCH → 重签 → 重试一次
+ *   401 SIGNER_MISMATCH / PATH_MISMATCH / CHAIN_MISMATCH → 直接抛错
+ *   402 → ApprovalRequiredError
+ *   403 → NotRegisteredError
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BscAgent = void 0;
+const ethers_1 = require("ethers");
+const errors_1 = require("./errors");
+const REGISTRY_ABI = [
+    'function agents(address) view returns (bool registered, uint256 deposit, int256 score, bool slashed)',
+    'function getScore(address) view returns (int256)',
+    'function getCreditLimit(address) view returns (uint256)',
+    'function TOKEN_DECIMALS() view returns (uint8)',
+    'function DEPOSIT() view returns (uint256)',
+    'function operator() view returns (address)',
+    'function ledger() view returns (address)',
+    'function register()',
+    'function recordPrePayment(address)',
+];
+const LEDGER_ABI = [
+    'function getDebt(address) view returns (uint256)',
+    'function getDebtDueTime(address) view returns (uint256)',
+    'function settle()',
+    'function operator() view returns (address)',
+    'function registry() view returns (address)',
+];
+const ERC20_ABI = [
+    'function balanceOf(address) view returns (uint256)',
+    'function allowance(address,address) view returns (uint256)',
+    'function approve(address,uint256) returns (bool)',
+];
+const PAYMENT_AUTH_TYPES = {
+    PaymentAuth: [
+        { name: 'agent', type: 'address' },
+        { name: 'method', type: 'string' },
+        { name: 'path', type: 'string' },
+        { name: 'price', type: 'uint256' },
+        { name: 'chainId', type: 'uint256' },
+        { name: 'timestamp', type: 'uint256' },
+        { name: 'nonce', type: 'bytes32' },
+    ],
+};
+class BscAgent {
+    constructor(config) {
+        this.config = config;
+        // 由 setup() 填充，测试可通过子类覆盖
+        this.operatorAddress = '';
+        this.depositAmount = 0n;
+        this.pricePerCall = 0n;
+        this.initialized = false;
+        const rpc = config.rpcUrl ?? 'https://bsc-dataseed.binance.org';
+        this.provider = new ethers_1.ethers.JsonRpcProvider(rpc);
+        this.wallet = new ethers_1.ethers.Wallet(config.privateKey, this.provider);
+        this.registry = new ethers_1.ethers.Contract(config.registryAddress, REGISTRY_ABI, this.wallet);
+        this.ledger = new ethers_1.ethers.Contract(config.ledgerAddress, LEDGER_ABI, this.wallet);
+        this.usdc = new ethers_1.ethers.Contract(config.usdcAddress, ERC20_ABI, this.wallet);
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // setup()
+    // ═══════════════════════════════════════════════════════════════════════════
+    async setup() {
+        const expectedChainId = this.config.chainId ?? 56;
+        const network = await this.provider.getNetwork();
+        if (Number(network.chainId) !== expectedChainId) {
+            throw new errors_1.InvalidAddressError(`chainId mismatch: expected ${expectedChainId}, got ${network.chainId}`);
+        }
+        const [operator, deposit, onChainLedger] = await Promise.all([
+            this.registry.operator(),
+            this.registry.DEPOSIT(),
+            this.registry.ledger(),
+        ]);
+        if (onChainLedger.toLowerCase() !== this.config.ledgerAddress.toLowerCase()) {
+            throw new errors_1.ContractRevertError('registry.ledger()', `Mismatch: ${onChainLedger} vs ${this.config.ledgerAddress}`);
+        }
+        this.operatorAddress = operator;
+        this.depositAmount = deposit;
+        if (this.config.pricePerCall !== undefined) {
+            this.pricePerCall = this.config.pricePerCall;
+        }
+        else {
+            this.pricePerCall = await this.fetchPriceFromGateway();
+        }
+        const [agentData, debt, creditLimit, nativeBal, usdcBal] = await Promise.all([
+            this.registry.agents(this.wallet.address),
+            this.ledger.getDebt(this.wallet.address),
+            this.registry.getCreditLimit(this.wallet.address),
+            this.provider.getBalance(this.wallet.address),
+            this.usdc.balanceOf(this.wallet.address),
+        ]);
+        this.initialized = true;
+        return {
+            address: this.wallet.address,
+            chainId: expectedChainId,
+            nativeBalance: nativeBal,
+            usdcBalance: usdcBal,
+            registered: agentData.registered,
+            debt,
+            creditLimit,
+            score: agentData.score,
+            pricePerCall: this.pricePerCall,
+            operatorAddress: this.operatorAddress,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // register()
+    // ═══════════════════════════════════════════════════════════════════════════
+    async register() {
+        const agentData = await this.registry.agents(this.wallet.address);
+        if (agentData.registered) {
+            return { didSendTx: false, alreadyRegistered: true };
+        }
+        const [balance, allowance] = await Promise.all([
+            this.usdc.balanceOf(this.wallet.address),
+            this.usdc.allowance(this.wallet.address, this.config.registryAddress),
+        ]);
+        if (balance < this.depositAmount) {
+            throw new errors_1.InsufficientBalanceError(this.depositAmount, balance, 'USDC');
+        }
+        if (allowance < this.depositAmount) {
+            throw new errors_1.ApprovalRequiredError(this.depositAmount, allowance, this.config.registryAddress, this.config.usdcAddress);
+        }
+        const scoreBefore = agentData.score;
+        let tx;
+        try {
+            tx = await this.registry.register();
+            await tx.wait();
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new errors_1.ContractRevertError('registry.register()', msg);
+        }
+        return {
+            didSendTx: true,
+            alreadyRegistered: false,
+            tx: tx.hash,
+            agent: this.wallet.address,
+            depositAmount: this.depositAmount,
+            scoreBefore,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // approve 三件套
+    // ═══════════════════════════════════════════════════════════════════════════
+    async approveRegistry(amount) {
+        return this._approve(this.config.registryAddress, amount);
+    }
+    async approveOperator(amount) {
+        if (!this.operatorAddress)
+            throw new errors_1.AuthRequiredError();
+        return this._approve(this.operatorAddress, amount);
+    }
+    async approveLedger(amount) {
+        return this._approve(this.config.ledgerAddress, amount);
+    }
+    async _approve(spender, amount) {
+        let tx;
+        try {
+            tx = await this.usdc.approve(spender, amount);
+            await tx.wait();
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new errors_1.ContractRevertError(`usdc.approve(${spender})`, msg);
+        }
+        return { tx: tx.hash, spender, amount };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // call()
+    // ═══════════════════════════════════════════════════════════════════════════
+    async call(resource) {
+        if (!this.initialized)
+            throw new errors_1.AuthRequiredError();
+        const canonicalPath = '/' + resource.replace(/^\/+/, '').split('?')[0];
+        const url = this.config.gatewayUrl.replace(/\/$/, '') + canonicalPath;
+        const attempt = async (price) => {
+            const payload = await this.signPaymentAuth(canonicalPath, price);
+            try {
+                return await fetch(url, {
+                    headers: { 'X-SOVRx402-Signature': JSON.stringify(payload) },
+                });
+            }
+            catch (e) {
+                throw new errors_1.NetworkError(url, undefined, e);
+            }
+        };
+        let resp = await attempt(this.pricePerCall);
+        if (resp.ok) {
+            return { success: true, data: await resp.json() };
+        }
+        // ── 非 200 处理 ──────────────────────────────────────────────────────────
+        if (resp.status === 402) {
+            throw new errors_1.ApprovalRequiredError(this.pricePerCall, 0n, this.operatorAddress, this.config.usdcAddress);
+        }
+        if (resp.status === 403) {
+            throw new errors_1.NotRegisteredError(this.wallet.address, this.config.registryAddress);
+        }
+        if (resp.status !== 401) {
+            throw new errors_1.GatewayError(resp.status, await resp.json().catch(() => null));
+        }
+        // ── 401：解析错误，决定是否重试 ──────────────────────────────────────────
+        const body = await resp.json();
+        const { code, reason } = body;
+        // 不重试的错误
+        if (reason === 'SIGNER_MISMATCH')
+            throw new errors_1.AuthInvalidError('SIGNER_MISMATCH');
+        if (reason === 'PATH_MISMATCH')
+            throw new errors_1.AuthInvalidError('PATH_MISMATCH');
+        if (reason === 'CHAIN_MISMATCH')
+            throw new errors_1.AuthInvalidError('CHAIN_MISMATCH');
+        if (reason === 'SIGNATURE_MALFORMED')
+            throw new errors_1.AuthInvalidError('SIGNATURE_MALFORMED');
+        if (reason === 'HEADER_MISSING')
+            throw new errors_1.AuthRequiredError();
+        // PRICE_MISMATCH：刷新 pricePerCall
+        if (reason === 'PRICE_MISMATCH') {
+            try {
+                const freshPrice = await this.fetchPriceFromGateway();
+                this.pricePerCall = freshPrice;
+            }
+            catch {
+                // 拉取失败则继续用当前 price 重试
+            }
+        }
+        // 可重试：PRICE_MISMATCH / AUTH_EXPIRED / NONCE_REUSED
+        const retryResp = await attempt(this.pricePerCall);
+        if (retryResp.ok) {
+            return { success: true, data: await retryResp.json() };
+        }
+        // 重试仍失败 → 抛对应错误
+        if (code === 'AUTH_EXPIRED')
+            throw new errors_1.AuthExpiredError(reason);
+        if (code === 'NONCE_REUSED')
+            throw new errors_1.NonceReusedError();
+        if (code === 'AUTH_INVALID')
+            throw new errors_1.AuthInvalidError(reason);
+        throw new errors_1.GatewayError(retryResp.status, await retryResp.json().catch(() => null));
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // settle()
+    // ═══════════════════════════════════════════════════════════════════════════
+    async settle() {
+        const debt = await this.ledger.getDebt(this.wallet.address);
+        if (debt === 0n) {
+            const score = await this.registry.getScore(this.wallet.address);
+            return { didSendTx: false, amountPaid: 0n, scoreAfter: score };
+        }
+        const [balance, allowance] = await Promise.all([
+            this.usdc.balanceOf(this.wallet.address),
+            this.usdc.allowance(this.wallet.address, this.config.ledgerAddress),
+        ]);
+        if (balance < debt) {
+            throw new errors_1.InsufficientBalanceError(debt, balance, 'USDC');
+        }
+        if (allowance < debt) {
+            throw new errors_1.ApprovalRequiredError(debt, allowance, this.config.ledgerAddress, this.config.usdcAddress);
+        }
+        let tx;
+        try {
+            tx = await this.ledger.settle();
+            await tx.wait();
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            throw new errors_1.ContractRevertError('ledger.settle()', msg);
+        }
+        const scoreAfter = await this.registry.getScore(this.wallet.address);
+        return { didSendTx: true, tx: tx.hash, amountPaid: debt, scoreAfter };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // getStatus()
+    // ═══════════════════════════════════════════════════════════════════════════
+    async getStatus() {
+        const [agentData, debt, debtDueTime, creditLimit, nativeBal, usdcBal, allowance] = await Promise.all([
+            this.registry.agents(this.wallet.address),
+            this.ledger.getDebt(this.wallet.address),
+            this.ledger.getDebtDueTime(this.wallet.address),
+            this.registry.getCreditLimit(this.wallet.address),
+            this.provider.getBalance(this.wallet.address),
+            this.usdc.balanceOf(this.wallet.address),
+            this.usdc.allowance(this.wallet.address, this.operatorAddress || ethers_1.ethers.ZeroAddress),
+        ]);
+        const canCall = (allowance >= this.pricePerCall) ||
+            (debt + this.pricePerCall <= creditLimit);
+        return {
+            address: this.wallet.address,
+            chainId: this.config.chainId ?? 56,
+            nativeBalance: nativeBal,
+            usdcBalance: usdcBal,
+            registered: agentData.registered,
+            slashed: agentData.slashed,
+            debt,
+            debtDueTime: Number(debtDueTime),
+            creditLimit,
+            score: agentData.score,
+            allowance,
+            pricePerCall: this.pricePerCall,
+            canCall,
+        };
+    }
+    // ═══════════════════════════════════════════════════════════════════════════
+    // 内部工具
+    // ═══════════════════════════════════════════════════════════════════════════
+    async signPaymentAuth(canonicalPath, price) {
+        const chainId = this.config.chainId ?? 56;
+        const nonce = ethers_1.ethers.hexlify(ethers_1.ethers.randomBytes(32));
+        const timestamp = Math.floor(Date.now() / 1000) - 1; // 避免 FUTURE_TIMESTAMP
+        const domain = {
+            name: 'SOVRx402BSCGateway',
+            version: '1',
+            chainId,
+            verifyingContract: this.config.registryAddress,
+        };
+        const value = {
+            agent: this.wallet.address,
+            method: 'GET',
+            path: canonicalPath,
+            price,
+            chainId: BigInt(chainId),
+            timestamp: BigInt(timestamp),
+            nonce,
+        };
+        const signature = await this.wallet.signTypedData(domain, PAYMENT_AUTH_TYPES, value);
+        return {
+            agent: this.wallet.address,
+            method: 'GET',
+            path: canonicalPath,
+            price: price.toString(),
+            chainId,
+            timestamp,
+            nonce,
+            signature,
+        };
+    }
+    async fetchPriceFromGateway() {
+        const gatewayBase = this.config.gatewayUrl.replace(/\/$/, '');
+        let resp;
+        try {
+            resp = await fetch(`${gatewayBase}/status?agent=${this.wallet.address}`);
+        }
+        catch (e) {
+            throw new errors_1.NetworkError(gatewayBase + '/status', undefined, e);
+        }
+        if (!resp.ok)
+            throw new errors_1.GatewayError(resp.status, await resp.json().catch(() => null));
+        const data = await resp.json();
+        if (!data.pricePerCall)
+            throw new errors_1.GatewayError(200, { detail: 'pricePerCall missing' });
+        return BigInt(data.pricePerCall);
+    }
+}
+exports.BscAgent = BscAgent;

package/dist/errors.d.ts

@@ -0,0 +1,90 @@
+/**
+ * SOVRx402 Agent SDK — Machine-readable error types
+ * 禁止使用字符串 message 作为主要信息载体
+ */
+export declare abstract class SOVRx402BaseError extends Error {
+    abstract readonly type: string;
+}
+export declare class NetworkError extends SOVRx402BaseError {
+    readonly url: string;
+    readonly statusCode?: number | undefined;
+    readonly type: "NETWORK_ERROR";
+    constructor(url: string, statusCode?: number | undefined, cause?: unknown);
+}
+export declare class NotRegisteredError extends SOVRx402BaseError {
+    readonly agent: string;
+    readonly registryAddress: string;
+    readonly type: "NOT_REGISTERED";
+    constructor(agent: string, registryAddress: string);
+}
+export declare class InvalidAddressError extends SOVRx402BaseError {
+    readonly address: string;
+    readonly type: "INVALID_ADDRESS";
+    constructor(address: string);
+}
+export declare class ApprovalRequiredError extends SOVRx402BaseError {
+    readonly required: bigint;
+    readonly current: bigint;
+    readonly spender: string;
+    readonly token: string;
+    readonly type: "APPROVAL_REQUIRED";
+    constructor(required: bigint, current: bigint, spender: string, token: string);
+}
+export declare class InsufficientBalanceError extends SOVRx402BaseError {
+    readonly required: bigint;
+    readonly current: bigint;
+    readonly token: 'USDC' | 'native';
+    readonly type: "INSUFFICIENT_BALANCE";
+    constructor(required: bigint, current: bigint, token: 'USDC' | 'native');
+}
+export declare class CreditExhaustedError extends SOVRx402BaseError {
+    readonly debt: bigint;
+    readonly creditLimit: bigint;
+    readonly type: "CREDIT_EXHAUSTED";
+    constructor(debt: bigint, creditLimit: bigint);
+}
+export declare class PaymentRejectedError extends SOVRx402BaseError {
+    readonly gatewayCode: string;
+    readonly gatewayReason: string;
+    readonly type: "PAYMENT_REJECTED";
+    constructor(gatewayCode: string, gatewayReason: string);
+}
+export declare class TransferFailedError extends SOVRx402BaseError {
+    readonly attempt?: string | undefined;
+    readonly txHash?: string | undefined;
+    readonly type: "TRANSFER_FAILED";
+    constructor(attempt?: string | undefined, txHash?: string | undefined);
+}
+export declare class GatewayError extends SOVRx402BaseError {
+    readonly statusCode: number;
+    readonly body: unknown;
+    readonly type: "GATEWAY_ERROR";
+    constructor(statusCode: number, body: unknown);
+}
+export declare class ContractRevertError extends SOVRx402BaseError {
+    readonly method: string;
+    readonly revertReason?: string | undefined;
+    readonly type: "CONTRACT_REVERT";
+    constructor(method: string, revertReason?: string | undefined);
+}
+export declare class AuthRequiredError extends SOVRx402BaseError {
+    readonly type: "AUTH_REQUIRED";
+    constructor();
+}
+export type AuthInvalidReason = 'CHAIN_MISMATCH' | 'SIGNATURE_MALFORMED' | 'SIGNER_MISMATCH' | 'PRICE_MISMATCH' | 'PATH_MISMATCH';
+export declare class AuthInvalidError extends SOVRx402BaseError {
+    readonly reason: AuthInvalidReason;
+    readonly type: "AUTH_INVALID";
+    constructor(reason: AuthInvalidReason);
+}
+export type AuthExpiredReason = 'FUTURE_TIMESTAMP' | 'TOO_OLD';
+export declare class AuthExpiredError extends SOVRx402BaseError {
+    readonly reason: AuthExpiredReason;
+    readonly type: "AUTH_EXPIRED";
+    constructor(reason: AuthExpiredReason);
+}
+export declare class NonceReusedError extends SOVRx402BaseError {
+    readonly type: "NONCE_REUSED";
+    constructor();
+}
+export type SOVRx402Error = NetworkError | NotRegisteredError | ApprovalRequiredError | InsufficientBalanceError | CreditExhaustedError | PaymentRejectedError | TransferFailedError | GatewayError | ContractRevertError | InvalidAddressError | AuthRequiredError | AuthInvalidError | AuthExpiredError | NonceReusedError;

package/dist/errors.js

@@ -0,0 +1,140 @@
+"use strict";
+/**
+ * SOVRx402 Agent SDK — Machine-readable error types
+ * 禁止使用字符串 message 作为主要信息载体
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NonceReusedError = exports.AuthExpiredError = exports.AuthInvalidError = exports.AuthRequiredError = exports.ContractRevertError = exports.GatewayError = exports.TransferFailedError = exports.PaymentRejectedError = exports.CreditExhaustedError = exports.InsufficientBalanceError = exports.ApprovalRequiredError = exports.InvalidAddressError = exports.NotRegisteredError = exports.NetworkError = exports.SOVRx402BaseError = void 0;
+class SOVRx402BaseError extends Error {
+}
+exports.SOVRx402BaseError = SOVRx402BaseError;
+// ── 网络层 ────────────────────────────────────────────────────────────────
+class NetworkError extends SOVRx402BaseError {
+    constructor(url, statusCode, cause) {
+        super(`Network error: ${url}${statusCode ? ` (${statusCode})` : ''}`);
+        this.url = url;
+        this.statusCode = statusCode;
+        this.type = 'NETWORK_ERROR';
+        if (cause instanceof Error)
+            this.cause = cause;
+    }
+}
+exports.NetworkError = NetworkError;
+// ── 注册 / 身份 ────────────────────────────────────────────────────────────
+class NotRegisteredError extends SOVRx402BaseError {
+    constructor(agent, registryAddress) {
+        super(`Agent ${agent} not registered in ${registryAddress}`);
+        this.agent = agent;
+        this.registryAddress = registryAddress;
+        this.type = 'NOT_REGISTERED';
+    }
+}
+exports.NotRegisteredError = NotRegisteredError;
+class InvalidAddressError extends SOVRx402BaseError {
+    constructor(address) {
+        super(`Invalid address: ${address}`);
+        this.address = address;
+        this.type = 'INVALID_ADDRESS';
+    }
+}
+exports.InvalidAddressError = InvalidAddressError;
+// ── 资金 / 授权 ────────────────────────────────────────────────────────────
+class ApprovalRequiredError extends SOVRx402BaseError {
+    constructor(required, current, spender, token) {
+        super(`Approval required: ${required} to ${spender}`);
+        this.required = required;
+        this.current = current;
+        this.spender = spender;
+        this.token = token;
+        this.type = 'APPROVAL_REQUIRED';
+    }
+}
+exports.ApprovalRequiredError = ApprovalRequiredError;
+class InsufficientBalanceError extends SOVRx402BaseError {
+    constructor(required, current, token) {
+        super(`Insufficient ${token} balance: need ${required}, have ${current}`);
+        this.required = required;
+        this.current = current;
+        this.token = token;
+        this.type = 'INSUFFICIENT_BALANCE';
+    }
+}
+exports.InsufficientBalanceError = InsufficientBalanceError;
+class CreditExhaustedError extends SOVRx402BaseError {
+    constructor(debt, creditLimit) {
+        super(`Credit exhausted: debt=${debt}, limit=${creditLimit}`);
+        this.debt = debt;
+        this.creditLimit = creditLimit;
+        this.type = 'CREDIT_EXHAUSTED';
+    }
+}
+exports.CreditExhaustedError = CreditExhaustedError;
+// ── 支付 ──────────────────────────────────────────────────────────────────
+class PaymentRejectedError extends SOVRx402BaseError {
+    constructor(gatewayCode, gatewayReason) {
+        super(`Payment rejected: ${gatewayCode}/${gatewayReason}`);
+        this.gatewayCode = gatewayCode;
+        this.gatewayReason = gatewayReason;
+        this.type = 'PAYMENT_REJECTED';
+    }
+}
+exports.PaymentRejectedError = PaymentRejectedError;
+class TransferFailedError extends SOVRx402BaseError {
+    constructor(attempt, txHash) {
+        super(`Transfer failed${attempt ? `: ${attempt}` : ''}`);
+        this.attempt = attempt;
+        this.txHash = txHash;
+        this.type = 'TRANSFER_FAILED';
+    }
+}
+exports.TransferFailedError = TransferFailedError;
+// ── 网关 / 合约 ────────────────────────────────────────────────────────────
+class GatewayError extends SOVRx402BaseError {
+    constructor(statusCode, body) {
+        super(`Gateway error: ${statusCode}`);
+        this.statusCode = statusCode;
+        this.body = body;
+        this.type = 'GATEWAY_ERROR';
+    }
+}
+exports.GatewayError = GatewayError;
+class ContractRevertError extends SOVRx402BaseError {
+    constructor(method, revertReason) {
+        super(`Contract revert in ${method}: ${revertReason ?? 'unknown'}`);
+        this.method = method;
+        this.revertReason = revertReason;
+        this.type = 'CONTRACT_REVERT';
+    }
+}
+exports.ContractRevertError = ContractRevertError;
+// ── Auth 错误（对应 auth-bsc.ts 的服务端错误，客户端镜像）─────────────────
+class AuthRequiredError extends SOVRx402BaseError {
+    constructor() {
+        super('Authentication required');
+        this.type = 'AUTH_REQUIRED';
+    }
+}
+exports.AuthRequiredError = AuthRequiredError;
+class AuthInvalidError extends SOVRx402BaseError {
+    constructor(reason) {
+        super(`Auth invalid: ${reason}`);
+        this.reason = reason;
+        this.type = 'AUTH_INVALID';
+    }
+}
+exports.AuthInvalidError = AuthInvalidError;
+class AuthExpiredError extends SOVRx402BaseError {
+    constructor(reason) {
+        super(`Auth expired: ${reason}`);
+        this.reason = reason;
+        this.type = 'AUTH_EXPIRED';
+    }
+}
+exports.AuthExpiredError = AuthExpiredError;
+class NonceReusedError extends SOVRx402BaseError {
+    constructor() {
+        super('Nonce already used');
+        this.type = 'NONCE_REUSED';
+    }
+}
+exports.NonceReusedError = NonceReusedError;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { BaseAgent } from './BaseAgent';
+export { BscAgent } from './BscAgent';
+export * from './errors';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BscAgent = exports.BaseAgent = void 0;
+var BaseAgent_1 = require("./BaseAgent");
+Object.defineProperty(exports, "BaseAgent", { enumerable: true, get: function () { return BaseAgent_1.BaseAgent; } });
+var BscAgent_1 = require("./BscAgent");
+Object.defineProperty(exports, "BscAgent", { enumerable: true, get: function () { return BscAgent_1.BscAgent; } });
+__exportStar(require("./errors"), exports);
+__exportStar(require("./types"), exports);

package/dist/types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * SOVRx402 Agent SDK — 类型定义
+ */
+export interface BaseAgentConfig {
+    /** Agent 私钥（hex 格式，0x 前缀） */
+    privateKey: string;
+    /** 网关 URL，e.g. http://localhost:3000 */
+    gatewayUrl: string;
+    /** Base 主网 USDC 合约地址 */
+    usdcAddress: string;
+    /** RPC 端点，默认 mainnet.base.org */
+    rpcUrl?: string;
+    /** x402 facilitator URL，默认 CDP */
+    facilitatorUrl?: string;
+}
+export interface BscAgentConfig {
+    /** Agent 私钥（hex 格式，0x 前缀） */
+    privateKey: string;
+    /** 网关 URL，e.g. http://localhost:3001 */
+    gatewayUrl: string;
+    /** BSC USDC 合约地址 */
+    usdcAddress: string;
+    /** SOVRx402Registry 合约地址 */
+    registryAddress: string;
+    /** CreditLedger 合约地址 */
+    ledgerAddress: string;
+    /** RPC 端点，默认 bsc-dataseed.binance.org */
+    rpcUrl?: string;
+    /** chainId，默认 56 */
+    chainId?: number;
+    /** 每次调用价格（bigint），若省略则在 setup() 时从 /status 读取 */
+    pricePerCall?: bigint;
+}
+export interface SetupResult {
+    address: string;
+    chainId: number;
+    nativeBalance: bigint;
+    usdcBalance: bigint;
+    registered?: boolean;
+    debt?: bigint;
+    creditLimit?: bigint;
+    score?: bigint;
+    pricePerCall?: bigint;
+    operatorAddress?: string;
+}
+export interface RegisterResult {
+    didSendTx: boolean;
+    alreadyRegistered: boolean;
+    tx?: string;
+    agent?: string;
+    depositAmount?: bigint;
+    scoreBefore?: bigint;
+}
+export interface ApproveResult {
+    tx: string;
+    spender: string;
+    amount: bigint;
+}
+export interface CallResult {
+    success: boolean;
+    data: unknown;
+    path?: 'credit' | 'prepay';
+    tx?: string;
+}
+export interface SettleResult {
+    didSendTx: boolean;
+    tx?: string;
+    amountPaid: bigint;
+    scoreAfter: bigint;
+}
+export interface AgentStatus {
+    address: string;
+    chainId: number;
+    nativeBalance: bigint;
+    usdcBalance: bigint;
+    registered?: boolean;
+    slashed?: boolean;
+    debt?: bigint;
+    debtDueTime?: number;
+    creditLimit?: bigint;
+    score?: bigint;
+    allowance?: bigint;
+    pricePerCall?: bigint;
+    canCall?: boolean;
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * SOVRx402 Agent SDK — 类型定义
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@sovrx402/agent-sdk",
+  "version": "1.0.0",
+  "description": "On-chain credit & payment infrastructure for AI agents",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "keywords": [
+    "web3",
+    "ai",
+    "agent",
+    "payment",
+    "x402",
+    "eip712",
+    "usdc",
+    "bsc",
+    "base"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "ethers": "^6.0.0"
+  }
+}