mppx 0.8.4 → 0.8.5

package/src/x402/Assets.test.ts

@@ -0,0 +1,211 @@
+import { usdc } from 'viem/tokens'
+import { describe, expect, test } from 'vp/test'
+
+import * as Assets from './Assets.js'
+
+describe('x402 assets', () => {
+  test('defines branded asset metadata', () => {
+    const asset = Assets.define({
+      address: '0x1111111111111111111111111111111111111111',
+      decimals: 18,
+      network: 'eip155:1',
+      transfer: {
+        name: 'USD Coin',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+
+    expect(Assets.isAsset(asset)).toBe(true)
+    expect(asset).toMatchObject({
+      address: '0x1111111111111111111111111111111111111111',
+      decimals: 18,
+      network: 'eip155:1',
+      transfer: {
+        name: 'USD Coin',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+  })
+
+  test('rejects unbranded values', () => {
+    expect(Assets.isAsset(null)).toBe(false)
+    expect(Assets.isAsset('0x1111111111111111111111111111111111111111')).toBe(false)
+    expect(
+      Assets.isAsset({
+        address: '0x1111111111111111111111111111111111111111',
+        decimals: 18,
+        network: 'eip155:1',
+        transfer: {
+          name: 'USD Coin',
+          type: 'eip3009',
+          version: '2',
+        },
+      }),
+    ).toBe(false)
+  })
+
+  test('defines asset metadata from viem tokens', () => {
+    const asset = Assets.fromToken(usdc, {
+      chainId: 84532,
+      transfer: {
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+
+    expect(Assets.isAsset(asset)).toBe(true)
+    expect(asset).toMatchObject({
+      address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      decimals: 6,
+      network: 'eip155:84532',
+      transfer: {
+        name: 'USD Coin',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+  })
+
+  test('allows viem token transfer metadata overrides', () => {
+    const eip3009Asset = Assets.fromToken(usdc, {
+      chainId: 84532,
+      transfer: {
+        name: 'USDC',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+    const permit2Asset = Assets.fromToken(usdc, {
+      chainId: 84532,
+      transfer: {
+        type: 'permit2',
+      },
+    })
+
+    expect(eip3009Asset.transfer).toEqual({
+      name: 'USDC',
+      type: 'eip3009',
+      version: '2',
+    })
+    expect(permit2Asset.transfer).toEqual({
+      type: 'permit2',
+    })
+  })
+
+  test('requires token names for EIP-3009 viem token assets', () => {
+    const tokenWithoutName = Object.assign(
+      () => ({
+        address: '0x1111111111111111111111111111111111111111',
+        decimals: 6,
+        symbol: 'TEST',
+      }),
+      {
+        addresses: { 1: '0x1111111111111111111111111111111111111111' },
+        decimals: 6,
+      },
+    ) as unknown as Assets.ViemToken
+
+    expect(() =>
+      Assets.fromToken(tokenWithoutName, {
+        chainId: 1,
+        transfer: {
+          type: 'eip3009',
+          version: '2',
+        },
+      }),
+    ).toThrow('EIP-3009 token assets require a token name.')
+  })
+
+  test('identifies currency kinds and converts networks', () => {
+    expect(Assets.isToken(usdc)).toBe(true)
+    expect(Assets.isToken(Assets.baseSepolia.USDC)).toBe(false)
+    expect(Assets.isRawAddress('0x1111111111111111111111111111111111111111')).toBe(true)
+    expect(Assets.isRawAddress(Assets.baseSepolia.USDC)).toBe(false)
+    expect(Assets.toNetwork(84532)).toBe('eip155:84532')
+    expect(Assets.toChainId('eip155:84532')).toBe(84532)
+  })
+
+  test('resolves and matches raw addresses, known assets, and viem tokens', () => {
+    expect(Assets.resolve('0x1111111111111111111111111111111111111111', 'eip155:84532')).toEqual({
+      address: '0x1111111111111111111111111111111111111111',
+    })
+    expect(Assets.resolve(Assets.baseSepolia.USDC, 'eip155:84532')).toEqual({
+      address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      decimals: 6,
+      transfer: {
+        name: 'USDC',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+    expect(Assets.resolve(Assets.baseSepolia.USDC, 'eip155:8453')).toBeUndefined()
+    expect(Assets.resolve(usdc, 'eip155:84532')).toEqual({
+      address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      decimals: 6,
+      name: 'USD Coin',
+    })
+    expect(Assets.resolve(usdc, 'eip155:999999')).toBeUndefined()
+    expect(Assets.matches(usdc, '0x036CbD53842c5426634e7929541eC2318f3dCF7e', 'eip155:84532')).toBe(
+      true,
+    )
+    expect(Assets.matches(usdc, '0x036cbd53842c5426634e7929541ec2318f3dcf7e', 'eip155:84532')).toBe(
+      true,
+    )
+    expect(
+      Assets.matches(
+        '0x1111111111111111111111111111111111111111',
+        '0x1111111111111111111111111111111111111111',
+        'eip155:84532',
+      ),
+    ).toBe(true)
+    expect(
+      Assets.matches(
+        Assets.baseSepolia.USDC,
+        '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+        'eip155:84532',
+      ),
+    ).toBe(false)
+  })
+
+  test('throws when creating assets from tokens unavailable on a chain', () => {
+    expect(() =>
+      Assets.fromToken(usdc, {
+        chainId: 999_999,
+        transfer: {
+          type: 'eip3009',
+          version: '2',
+        },
+      }),
+    ).toThrow('Token has no address for chain id "999999".')
+  })
+
+  test('exports Base USDC metadata', () => {
+    expect(Assets.isAsset(Assets.base.USDC)).toBe(true)
+    expect(Assets.base.USDC).toMatchObject({
+      address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+      decimals: 6,
+      network: 'eip155:8453',
+      transfer: {
+        name: 'USD Coin',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+  })
+
+  test('exports Base Sepolia USDC metadata', () => {
+    expect(Assets.isAsset(Assets.baseSepolia.USDC)).toBe(true)
+    expect(Assets.baseSepolia.USDC).toMatchObject({
+      address: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
+      decimals: 6,
+      network: 'eip155:84532',
+      transfer: {
+        name: 'USDC',
+        type: 'eip3009',
+        version: '2',
+      },
+    })
+  })
+})

package/src/x402/Assets.ts

@@ -1,3 +1,6 @@
+import { getAddress } from 'viem'
+import type { Token } from 'viem/tokens'
+
 import type { Asset, EvmNetwork, ExactTransfer } from './Types.js'
 
 const knownAsset = Symbol('mppx.x402.asset')
@@ -8,6 +11,12 @@ export type KnownAsset = Asset & {
   network: EvmNetwork
 }
 
+/** Viem token metadata from `viem/tokens`. */
+export type ViemToken = Token
+
+/** Currency metadata accepted by EVM and x402 payment config. */
+export type Currency = `0x${string}` | KnownAsset | ViemToken
+
 /** Creates typed x402 asset metadata for custom tokens. */
 export function define(parameters: define.Parameters): KnownAsset {
   return {
@@ -28,6 +37,30 @@ export declare namespace define {
   }
 }
 
+/** Creates x402 asset metadata from a `viem/tokens` token definition. */
+export function fromToken(token: ViemToken, parameters: fromToken.Parameters): KnownAsset {
+  const resolved = token(parameters.chainId)
+  return define({
+    address: resolved.address,
+    decimals: resolved.decimals,
+    network: toNetwork(parameters.chainId),
+    transfer: withTokenDefaults(parameters.transfer, resolved),
+  })
+}
+
+export declare namespace fromToken {
+  type Parameters = {
+    chainId: number
+    transfer: Transfer
+  }
+
+  type Transfer =
+    | (Omit<Extract<ExactTransfer, { type: 'eip3009' }>, 'name'> & {
+        name?: string | undefined
+      })
+    | Extract<ExactTransfer, { type: 'permit2' }>
+}
+
 /** Base network known assets. */
 export const base = {
   USDC: define({
@@ -63,3 +96,86 @@ export function isAsset(value: unknown): value is KnownAsset {
   if (typeof value !== 'object' || value === null) return false
   return (value as Partial<KnownAsset>)[knownAsset] === true
 }
+
+/** Returns true when a value is a `viem/tokens` token definition. */
+export function isToken(value: unknown): value is ViemToken {
+  return (
+    typeof value === 'function' &&
+    typeof (value as Partial<ViemToken>).addresses === 'object' &&
+    typeof (value as Partial<ViemToken>).decimals === 'number'
+  )
+}
+
+/** Returns true when a currency is a raw address without chain metadata. */
+export function isRawAddress(currency: Currency): currency is `0x${string}` {
+  return typeof currency === 'string'
+}
+
+/** Resolves currency metadata for an EVM network. */
+export function resolve(currency: Currency, network: EvmNetwork): resolve.Result | undefined {
+  if (isAsset(currency)) {
+    if (currency.network !== network) return undefined
+    return {
+      address: currency.address,
+      decimals: currency.decimals,
+      transfer: currency.transfer,
+    }
+  }
+
+  if (isToken(currency)) {
+    const address = currency.addresses[toChainId(network)]
+    if (!address) return undefined
+    return {
+      address,
+      decimals: currency.decimals,
+      name: currency.name,
+    }
+  }
+
+  return {
+    address: currency,
+  }
+}
+
+export declare namespace resolve {
+  type Result = {
+    address: `0x${string}`
+    decimals?: number | undefined
+    name?: string | undefined
+    transfer?: ExactTransfer | undefined
+  }
+}
+
+/** Returns true when a currency resolves to the accepted address on the network. */
+export function matches(
+  currency: Currency,
+  acceptedCurrency: `0x${string}`,
+  network: EvmNetwork,
+): boolean {
+  const resolved = resolve(currency, network)
+  if (!resolved) return false
+  return getAddress(resolved.address) === getAddress(acceptedCurrency)
+}
+
+/** Converts an EVM chain ID to a CAIP-2 network identifier. */
+export function toNetwork(chainId: number): EvmNetwork {
+  return `eip155:${chainId}`
+}
+
+/** Converts a CAIP-2 EVM network identifier to a chain ID. */
+export function toChainId(network: EvmNetwork): number {
+  return Number(network.slice('eip155:'.length))
+}
+
+function withTokenDefaults(
+  transfer: fromToken.Transfer,
+  token: ReturnType<ViemToken>,
+): ExactTransfer {
+  if (transfer.type !== 'eip3009') return transfer
+  if (transfer.name) return { ...transfer, name: transfer.name }
+  if (!token.name) throw new Error('EIP-3009 token assets require a token name.')
+  return {
+    ...transfer,
+    name: token.name,
+  }
+}

package/src/x402/client/Exact.test.ts

@@ -1,5 +1,6 @@
 import { Challenge } from 'mppx'
 import type { Account } from 'viem'
+import { tokens } from 'viem/tokens'
 import { describe, expect, test, vi } from 'vp/test'
 
 import * as Chains from '../../evm/Chains.js'
@@ -78,6 +79,134 @@ describe('x402 exact credential helper', () => {
     ).rejects.toThrow('x402 exact raw currency allowlists require networks.')
   })
 
+  test('uses known asset metadata for currency policy and maxAmount decimals', async () => {
+    const signTypedData = vi.fn(async () => '0x1234')
+
+    const credential = await createCredential({
+      challenge: challenge(),
+      config: {
+        account: {
+          ...account,
+          signTypedData,
+        } as unknown as Account,
+        currencies: [Assets.baseSepolia.USDC],
+        maxAmount: '0.01',
+      },
+      context: {},
+    })
+    const paymentPayload = Header.decodePaymentSignature(credential)
+
+    expect(signTypedData).toHaveBeenCalledOnce()
+    expect(paymentPayload.accepted.asset).toBe(Assets.baseSepolia.USDC.address)
+  })
+
+  test('pins known asset currency policy to its network', async () => {
+    const signTypedData = vi.fn(async () => '0x1234')
+
+    await expect(
+      createCredential({
+        challenge: challenge({ network: 'eip155:8453' }),
+        config: {
+          account: {
+            ...account,
+            signTypedData,
+          } as unknown as Account,
+          currencies: [Assets.baseSepolia.USDC],
+          maxAmount: '0.01',
+        },
+        context: {},
+      }),
+    ).rejects.toThrow(
+      'x402 exact currency is not allowed: 0x036CbD53842c5426634e7929541eC2318f3dCF7e.',
+    )
+    expect(signTypedData).not.toHaveBeenCalled()
+  })
+
+  test('accepts viem token sets for currency policy and decimals', async () => {
+    const signTypedData = vi.fn(async () => '0x1234')
+
+    const credential = await createCredential({
+      challenge: challenge({ amount: '1000000' }),
+      config: {
+        account: {
+          ...account,
+          signTypedData,
+        } as unknown as Account,
+        currencies: tokens.popular,
+        maxAmount: '1',
+      },
+      context: {},
+    })
+    const paymentPayload = Header.decodePaymentSignature(credential)
+
+    expect(signTypedData).toHaveBeenCalledOnce()
+    expect(paymentPayload.accepted.asset).toBe(Assets.baseSepolia.USDC.address)
+  })
+
+  test('uses viem token decimals for maxAmount policy', async () => {
+    const signTypedData = vi.fn(async () => '0x1234')
+
+    await expect(
+      createCredential({
+        challenge: challenge({ amount: '1000001' }),
+        config: {
+          account: {
+            ...account,
+            signTypedData,
+          } as unknown as Account,
+          currencies: tokens.popular,
+          maxAmount: '1',
+        },
+        context: {},
+      }),
+    ).rejects.toThrow('x402 exact amount exceeds maxAmount.')
+    expect(signTypedData).not.toHaveBeenCalled()
+  })
+
+  test('accepts viem token sets through legacy assets policy', async () => {
+    const signTypedData = vi.fn(async () => '0x1234')
+
+    const credential = await createCredential({
+      challenge: challenge({ amount: '1000000' }),
+      config: {
+        account: {
+          ...account,
+          signTypedData,
+        } as unknown as Account,
+        assets: tokens.popular,
+        maxAmount: '1',
+      },
+      context: {},
+    })
+
+    expect(signTypedData).toHaveBeenCalledOnce()
+    expect(Header.decodePaymentSignature(credential).accepted.asset).toBe(
+      Assets.baseSepolia.USDC.address,
+    )
+  })
+
+  test('pins viem token currency policy to available networks', async () => {
+    const signTypedData = vi.fn(async () => '0x1234')
+
+    await expect(
+      createCredential({
+        challenge: challenge({ network: 'eip155:999999' }),
+        config: {
+          account: {
+            ...account,
+            signTypedData,
+          } as unknown as Account,
+          currencies: tokens.popular,
+          maxAmount: '1',
+        },
+        context: {},
+      }),
+    ).rejects.toThrow(
+      'x402 exact currency is not allowed: 0x036CbD53842c5426634e7929541eC2318f3dCF7e.',
+    )
+    expect(signTypedData).not.toHaveBeenCalled()
+  })
+
   test('signs EIP-3009 exact payment payloads', async () => {
     const signTypedData = vi.fn(async () => '0x1234')
     const config = {

package/src/x402/client/Exact.ts

@@ -99,9 +99,9 @@ export type Config = {
   /** Optional allowlist of supported EVM chain IDs. */
   networks?: readonly number[] | undefined
   /** Optional allowlist of supported currencies. */
-  currencies?: readonly (`0x${string}` | Assets.KnownAsset)[] | undefined
+  currencies?: readonly Assets.Currency[] | undefined
   /** Legacy alias for `currencies`. */
-  assets?: readonly (`0x${string}` | Assets.KnownAsset)[] | undefined
+  assets?: readonly Assets.Currency[] | undefined
 }
 
 const authorizationTypes = {
@@ -125,12 +125,12 @@ function assertPolicy(parameters: Config, accepted: Types.PaymentRequirements) {
     throw new Error(`x402 exact chain ID is not allowed: ${chainId}.`)
 
   const currencies = parameters.currencies ?? parameters.assets
-  if (currencies?.some((currency) => !Assets.isAsset(currency)) && !parameters.networks?.length)
+  if (currencies?.some((currency) => Assets.isRawAddress(currency)) && !parameters.networks?.length)
     throw new Error('x402 exact raw currency allowlists require networks.')
   if (currencies) {
     const acceptedCurrency = getAddress(accepted.asset as `0x${string}`)
     const allowed = currencies.some((currency) =>
-      currencyMatches(currency, acceptedCurrency, accepted.network),
+      Assets.matches(currency, acceptedCurrency, accepted.network),
     )
     if (!allowed) throw new Error(`x402 exact currency is not allowed: ${acceptedCurrency}.`)
   }
@@ -149,19 +149,6 @@ function assertPolicy(parameters: Config, accepted: Types.PaymentRequirements) {
   }
 }
 
-function addressOf(currency: `0x${string}` | Assets.KnownAsset): `0x${string}` {
-  return Assets.isAsset(currency) ? currency.address : currency
-}
-
-function currencyMatches(
-  currency: `0x${string}` | Assets.KnownAsset,
-  acceptedCurrency: `0x${string}`,
-  network: Types.EvmNetwork,
-): boolean {
-  if (getAddress(addressOf(currency)) !== acceptedCurrency) return false
-  return !Assets.isAsset(currency) || currency.network === network
-}
-
 function decimalsOfAcceptedCurrency(
   parameters: Config,
   accepted: Types.PaymentRequirements,
@@ -169,9 +156,10 @@ function decimalsOfAcceptedCurrency(
   const currencies = parameters.currencies ?? parameters.assets
   const acceptedCurrency = getAddress(accepted.asset as `0x${string}`)
   const currency = currencies?.find((currency) =>
-    currencyMatches(currency, acceptedCurrency, accepted.network),
+    Assets.matches(currency, acceptedCurrency, accepted.network),
   )
-  if (currency && Assets.isAsset(currency)) return currency.decimals
+  const resolved = currency ? Assets.resolve(currency, accepted.network) : undefined
+  if (resolved?.decimals !== undefined) return resolved.decimals
   return parameters.decimals
 }