Merge pull request #457 from nansen-ai/feat/x402-bsc-permit2-multi-asset

feat(x402): BSC multi-asset payments + Permit2 signing

Author: gulshngill

.changeset/x402-bsc-multi-asset-permit2.md

@@ -0,0 +1,5 @@
+---
+"nansen-cli": minor
+---
+
+x402 on BNB Smart Chain: support all four stablecoins the API now advertises (U, USD1, USDT, USDC) and add Permit2 payment signing. Payments route on the 402's `extra.assetTransferMethod` — `eip3009` keeps the existing gasless flow (U, USD1), while `permit2-exact` (USDT, USDC on BSC) signs a Permit2 `PermitWitnessTransferFrom` against the spender contract advertised in the 402. Permit2 entries are skipped with an actionable message when the wallet hasn't made the one-time `approve(Permit2, …)` for the token. Post-payment balance warnings now check the exact token paid with (per-token decimals) instead of one hardcoded token per network.

src/__tests__/x402-balance.test.js

@@ -3,8 +3,7 @@
  */
 
 import { describe, it, expect } from 'vitest';
-import { EVM_X402_TOKENS } from '../x402.js';
-import { CHAIN_RPCS } from '../rpc-urls.js';
+import { EVM_X402_TOKENS, EVM_X402_RPCS } from '../x402.js';
 
 describe('EVM_X402_TOKENS registry', () => {
   it('covers Base, X Layer, and BNB Smart Chain', () => {
@@ -13,26 +12,34 @@ describe('EVM_X402_TOKENS registry', () => {
     );
   });
 
-  it('uses 18 decimals for BSC USDT and 6 for the others', () => {
-    expect(EVM_X402_TOKENS['eip155:56'].decimals).toBe(18);
-    expect(EVM_X402_TOKENS['eip155:8453'].decimals).toBe(6);
-    expect(EVM_X402_TOKENS['eip155:196'].decimals).toBe(6);
+  it('lists the four BSC stablecoins with eip3009-capable tokens first', () => {
+    const symbols = EVM_X402_TOKENS['eip155:56'].map(t => t.symbol);
+    expect(symbols).toEqual(['U', 'USD1', 'USDT', 'USDC']);
+  });
+
+  it('uses 18 decimals for every BSC token and 6 elsewhere', () => {
+    for (const t of EVM_X402_TOKENS['eip155:56']) {
+      expect(t.decimals, t.symbol).toBe(18);
+    }
+    expect(EVM_X402_TOKENS['eip155:8453'][0].decimals).toBe(6);
+    expect(EVM_X402_TOKENS['eip155:196'][0].decimals).toBe(6);
   });
 
   it('pins the expected token contracts', () => {
-    expect(EVM_X402_TOKENS['eip155:8453'].token)
+    expect(EVM_X402_TOKENS['eip155:8453'][0].token)
       .toBe('0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'); // Base USDC
-    expect(EVM_X402_TOKENS['eip155:56'].token)
-      .toBe('0x55d398326f99059fF775485246999027B3197955'); // BSC USDT
+    const bsc = Object.fromEntries(
+      EVM_X402_TOKENS['eip155:56'].map(t => [t.symbol, t.token]),
+    );
+    expect(bsc.U).toBe('0xcE24439F2D9C6a2289F741120FE202248B666666');
+    expect(bsc.USD1).toBe('0x8d0d000ee44948fc98c9b98a4fa4921476f08b0d');
+    expect(bsc.USDT).toBe('0x55d398326f99059fF775485246999027B3197955');
+    expect(bsc.USDC).toBe('0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d');
   });
 
   it('resolves an RPC URL for every network', () => {
-    for (const [network, cfg] of Object.entries(EVM_X402_TOKENS)) {
-      expect(cfg.rpc, `rpc for ${network}`).toMatch(/^https?:\/\//);
+    for (const network of Object.keys(EVM_X402_TOKENS)) {
+      expect(EVM_X402_RPCS[network], `rpc for ${network}`).toMatch(/^https?:\/\//);
     }
   });
-
-  it('has a BSC entry in the shared RPC registry', () => {
-    expect(CHAIN_RPCS.bsc).toMatch(/^https?:\/\//);
-  });
 });

src/__tests__/x402-permit2.test.js

@@ -0,0 +1,136 @@
+/**
+ * Tests for Permit2 (permit2-exact) x402 payment signing.
+ *
+ * The digest test vector was computed with an independent EIP-712
+ * implementation (Python eth_account) over the same typed data, so it
+ * cross-validates the nested-struct hashing end to end.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  createEvmPaymentPayload,
+  createPermit2ExactPayload,
+  hashPermit2WitnessTransfer,
+  PERMIT2_ADDRESS,
+} from '../x402-evm.js';
+import { generateEvmWallet } from '../wallet.js';
+
+const REQUIREMENTS_PERMIT2 = {
+  scheme: 'exact',
+  network: 'eip155:56',
+  asset: '0x1000000000000000000000000000000000000001',
+  amount: '10000000000000000',
+  payTo: '0x3000000000000000000000000000000000000003',
+  maxTimeoutSeconds: 300,
+  extra: {
+    name: 'Test Token',
+    version: '1',
+    assetTransferMethod: 'permit2-exact',
+    signerAddress: '0x4000000000000000000000000000000000000004',
+    spenderAddress: '0x2000000000000000000000000000000000000002',
+  },
+};
+
+describe('hashPermit2WitnessTransfer', () => {
+  it('matches an independently computed EIP-712 digest', () => {
+    // Reference digest computed with Python eth_account over identical input.
+    const digest = hashPermit2WitnessTransfer(56, {
+      permitted: {
+        token: '0x1000000000000000000000000000000000000001',
+        amount: 10000000000000000n,
+      },
+      spender: '0x2000000000000000000000000000000000000002',
+      nonce: 123456789n,
+      deadline: 1750000000n,
+      witness: {
+        to: '0x3000000000000000000000000000000000000003',
+        validAfter: 1749999000n,
+      },
+    });
+    expect('0x' + digest.toString('hex')).toBe(
+      '0x84f21d844cc4f15e21f03e16da32687d28e4a1ce8bca3de73a5b8625f02c390b',
+    );
+  });
+
+  it('uses the canonical Permit2 contract address', () => {
+    expect(PERMIT2_ADDRESS).toBe('0x000000000022D473030F116dDEE9F6B43aC78BA3');
+  });
+});
+
+describe('createPermit2ExactPayload', () => {
+  it('builds a permit2Authorization payload with decimal-string fields', () => {
+    const wallet = generateEvmWallet();
+    const b64 = createPermit2ExactPayload(
+      REQUIREMENTS_PERMIT2, wallet.privateKey, wallet.address, 'https://api.example.com/x',
+    );
+    const payload = JSON.parse(Buffer.from(b64, 'base64').toString());
+
+    expect(payload.x402Version).toBe(2);
+    expect(payload.accepted).toEqual(REQUIREMENTS_PERMIT2);
+    expect(payload.resource).toEqual({ url: 'https://api.example.com/x' });
+
+    const auth = payload.payload.permit2Authorization;
+    expect(auth.from).toBe(wallet.address);
+    expect(auth.spender).toBe('0x2000000000000000000000000000000000000002');
+    expect(auth.permitted).toEqual({
+      token: REQUIREMENTS_PERMIT2.asset,
+      amount: REQUIREMENTS_PERMIT2.amount,
+    });
+    expect(auth.witness.to).toBe(REQUIREMENTS_PERMIT2.payTo);
+    // Wire-format numerics are decimal strings.
+    expect(auth.nonce).toMatch(/^\d+$/);
+    expect(auth.deadline).toMatch(/^\d+$/);
+    expect(auth.witness.validAfter).toMatch(/^\d+$/);
+    // EIP-3009 fields must be absent.
+    expect(payload.payload.authorization).toBeUndefined();
+    expect(payload.payload.signature).toMatch(/^0x[0-9a-f]{130}$/);
+  });
+
+  it('throws when spenderAddress is missing', () => {
+    const wallet = generateEvmWallet();
+    const req = {
+      ...REQUIREMENTS_PERMIT2,
+      extra: { ...REQUIREMENTS_PERMIT2.extra, spenderAddress: undefined },
+    };
+    expect(() =>
+      createPermit2ExactPayload(req, wallet.privateKey, wallet.address, 'u'),
+    ).toThrow(/spenderAddress/);
+  });
+});
+
+describe('createEvmPaymentPayload method routing', () => {
+  it('routes permit2-exact to the Permit2 payload', () => {
+    const wallet = generateEvmWallet();
+    const b64 = createEvmPaymentPayload(
+      REQUIREMENTS_PERMIT2, wallet.privateKey, wallet.address, 'u',
+    );
+    const payload = JSON.parse(Buffer.from(b64, 'base64').toString());
+    expect(payload.payload.permit2Authorization).toBeDefined();
+  });
+
+  it('keeps the EIP-3009 path when assetTransferMethod is eip3009 or absent', () => {
+    const wallet = generateEvmWallet();
+    for (const extra of [
+      { name: 'Test Token', version: '1' },
+      { name: 'Test Token', version: '1', assetTransferMethod: 'eip3009' },
+    ]) {
+      const b64 = createEvmPaymentPayload(
+        { ...REQUIREMENTS_PERMIT2, extra }, wallet.privateKey, wallet.address, 'u',
+      );
+      const payload = JSON.parse(Buffer.from(b64, 'base64').toString());
+      expect(payload.payload.authorization).toBeDefined();
+      expect(payload.payload.permit2Authorization).toBeUndefined();
+    }
+  });
+
+  it('throws on unsupported transfer methods so fallback can continue', () => {
+    const wallet = generateEvmWallet();
+    const req = {
+      ...REQUIREMENTS_PERMIT2,
+      extra: { ...REQUIREMENTS_PERMIT2.extra, assetTransferMethod: 'permit2-upto' },
+    };
+    expect(() =>
+      createEvmPaymentPayload(req, wallet.privateKey, wallet.address, 'u'),
+    ).toThrow(/assetTransferMethod/);
+  });
+});

src/api.js

@@ -493,7 +493,7 @@ export class NansenAPI {
    * an attemptX402Payment() method so adding a new payment provider only requires
    * touching that one method, not hunting inside the retry loop.
    */
-  async _x402Retry(signature, walletLabel, network, url, body, options = {}) {
+  async _x402Retry(signature, walletLabel, network, url, body, options = {}, asset = null) {
     const paidResponse = await fetch(url, {
       method: 'POST',
       headers: {
@@ -514,7 +514,7 @@ export class NansenAPI {
     if (network) {
       try {
         const { checkX402Balance } = await import('./x402.js');
-        const result = await checkX402Balance(network);
+        const result = await checkX402Balance(network, asset);
         if (result !== null && result.balance < 0.25) {
           console.error(`[x402] Warning: ${result.symbol} balance low ($${result.balance.toFixed(2)}). Fund your wallet to avoid interruptions.`);
         }
@@ -651,8 +651,8 @@ export class NansenAPI {
               // 1. Try local wallet with fallback across payment networks
               try {
                 const { createPaymentSignatures } = await import('./x402.js');
-                for await (const { signature, network } of createPaymentSignatures(response, url)) {
-                  const result = await this._x402Retry(signature, `local wallet ${defaultWalletName}`, network, url, body, options);
+                for await (const { signature, network, asset } of createPaymentSignatures(response, url)) {
+                  const result = await this._x402Retry(signature, `local wallet ${defaultWalletName}`, network, url, body, options, asset);
                   if (result !== null) return result;
                   // This payment option was rejected, try next
                 }