feat(tempo): add funding requirements and policies

.changeset/tempo-funding.md

@@ -0,0 +1,11 @@
+---
+"ox": patch
+---
+
+Added Tempo funding codecs, unsigned requirement inference, policy rules with optional source ordering, source helpers, and access key funding authorization.
+
+```ts
+import { TransactionRequest } from 'ox/tempo'
+
+TransactionRequest.toRpc({ requireFunds: [{ sources: [] }] })
+```

package.json

@@ -781,6 +781,31 @@
       "types": "./dist/tempo/EarnShares.d.ts",
       "default": "./dist/tempo/EarnShares.js"
     },
+    "./tempo/FundingPolicy": {
+      "src": "./src/tempo/FundingPolicy.ts",
+      "types": "./dist/tempo/FundingPolicy.d.ts",
+      "default": "./dist/tempo/FundingPolicy.js"
+    },
+    "./tempo/FundingRequirement": {
+      "src": "./src/tempo/FundingRequirement.ts",
+      "types": "./dist/tempo/FundingRequirement.d.ts",
+      "default": "./dist/tempo/FundingRequirement.js"
+    },
+    "./tempo/FundingSource": {
+      "src": "./src/tempo/FundingSource.ts",
+      "types": "./dist/tempo/FundingSource.d.ts",
+      "default": "./dist/tempo/FundingSource.js"
+    },
+    "./tempo/FundingSourceDex": {
+      "src": "./src/tempo/FundingSourceDex.ts",
+      "types": "./dist/tempo/FundingSourceDex.d.ts",
+      "default": "./dist/tempo/FundingSourceDex.js"
+    },
+    "./tempo/FundingSourceEarn": {
+      "src": "./src/tempo/FundingSourceEarn.ts",
+      "types": "./dist/tempo/FundingSourceEarn.d.ts",
+      "default": "./dist/tempo/FundingSourceEarn.js"
+    },
     "./tempo/KeyAuthorization": {
       "src": "./src/tempo/KeyAuthorization.ts",
       "types": "./dist/tempo/KeyAuthorization.d.ts",
@@ -1226,6 +1251,16 @@
       "types": "./dist/zod/tempo/AuthorizationTempo.d.ts",
       "default": "./dist/zod/tempo/AuthorizationTempo.js"
     },
+    "./zod/tempo/FundingPolicy": {
+      "src": "./src/zod/tempo/FundingPolicy.ts",
+      "types": "./dist/zod/tempo/FundingPolicy.d.ts",
+      "default": "./dist/zod/tempo/FundingPolicy.js"
+    },
+    "./zod/tempo/FundingRequirement": {
+      "src": "./src/zod/tempo/FundingRequirement.ts",
+      "types": "./dist/zod/tempo/FundingRequirement.d.ts",
+      "default": "./dist/zod/tempo/FundingRequirement.js"
+    },
     "./zod/tempo/KeyAuthorization": {
       "src": "./src/zod/tempo/KeyAuthorization.ts",
       "types": "./dist/zod/tempo/KeyAuthorization.d.ts",

src/core/Frame.ts

@@ -241,7 +241,10 @@ export declare namespace fromRpc {
  * ```ts twoslash
  * import { Frame } from 'ox'
  *
- * const frame = Frame.from({ executionGas: 50_000n, mode: 'verify' })
+ * const frame = Frame.from({
+ *   executionGas: 50_000n,
+ *   mode: 'verify'
+ * })
  * const rpc = Frame.toRpc(frame)
  * ```
  *

src/core/TxEnvelope.ts

@@ -242,7 +242,9 @@ export declare namespace deserialize {
  *
  * const envelope = TransactionEnvelope.from({
  *   chainId: 1,
- *   frames: [Frame.from({ executionGas: 50_000n, mode: 'sender' })],
+ *   frames: [
+ *     Frame.from({ executionGas: 50_000n, mode: 'sender' })
+ *   ],
  *   sender: '0x70997970c51812dc3a010c7d01b50e0d17dc79c8'
  * })
  * ```

src/tempo/FundingPolicy.test.ts

@@ -0,0 +1,204 @@
+import { describe, expect, test } from 'vp/test'
+import * as Rlp from '../core/Rlp.js'
+import * as KeyAuthorization from './KeyAuthorization.js'
+import * as FundingPolicy from './FundingPolicy.js'
+
+const token = '0x0101010101010101010101010101010101010101' as const
+const target = '0x0202020202020202020202020202020202020202' as const
+const requirement = {
+  token,
+  amount: 50n,
+  sources: [{ target, data: '0xab' as const }],
+  slippageBps: 100,
+}
+
+const rules = {
+  enforceOrder: false,
+  maxSlippageBps: 100,
+  sources: { [token]: requirement.sources },
+}
+describe('encode', () => {
+  test('ABI encodes, decodes and hashes canonical rules', () => {
+    expect(FundingPolicy.decode(FundingPolicy.encode(rules))).toEqual(rules)
+    expect(FundingPolicy.hash(rules)).toMatch(/^0x[0-9a-f]{64}$/)
+    expect(() =>
+      FundingPolicy.decode(`${FundingPolicy.encode(rules)}00`),
+    ).toThrow()
+  })
+})
+
+describe('hash', () => {
+  test('canonical token order preserves significant source order', () => {
+    const second = '0x0303030303030303030303030303030303030303'
+    const first = {
+      ...rules,
+      sources: { [second]: requirement.sources, [token]: requirement.sources },
+    }
+    const reordered = {
+      ...rules,
+      sources: { [token]: requirement.sources, [second]: requirement.sources },
+    }
+    expect(FundingPolicy.encode(first)).toBe(FundingPolicy.encode(reordered))
+    const sources = [...requirement.sources, { target, data: '0xcd' as const }]
+    expect(
+      FundingPolicy.hash({ ...rules, sources: { [token]: sources } }),
+    ).not.toBe(
+      FundingPolicy.hash({
+        ...rules,
+        sources: { [token]: [...sources].reverse() },
+      }),
+    )
+  })
+})
+
+describe('toTuple', () => {
+  test('rejects invalid policy IDs and admins', () => {
+    for (const value of [
+      0n,
+      2n ** 64n,
+      { admins: [], rules },
+      { admins: [token, token], rules },
+    ])
+      expect(() => FundingPolicy.toTuple(value)).toThrow()
+  })
+})
+
+describe('toRoutes', () => {
+  test('maps source addresses to the contract ABI field', () => {
+    expect(FundingPolicy.toRoutes(rules)).toEqual([
+      { token, sources: [{ target, data: '0xab' }] },
+    ])
+  })
+})
+
+describe('toRpc', () => {
+  test('keeps the RPC target field', () => {
+    expect(FundingPolicy.toRpc({ admins: [token], rules })).toEqual({
+      admins: [token],
+      rules: {
+        enforceOrder: false,
+        maxSlippageBps: 100,
+        sources: { [token]: [{ target, data: '0xab' }] },
+      },
+    })
+  })
+})
+
+describe('fromRpc', () => {
+  test('preserves RPC source targets', () => {
+    expect(
+      FundingPolicy.fromRpc({
+        admins: [token],
+        rules: {
+          enforceOrder: false,
+          maxSlippageBps: 100,
+          sources: { [token]: [{ target, data: '0xab' }] },
+        },
+      }),
+    ).toEqual({ admins: [token], rules })
+  })
+})
+
+describe('fromTuple', () => {
+  test('decodes source targets', () => {
+    expect(
+      FundingPolicy.fromTuple([
+        [token],
+        ['0x64', [[token, [[target, '0xab']]]], '0x'],
+      ]),
+    ).toEqual({ admins: [token], rules })
+  })
+})
+
+describe('behavior', () => {
+  test.each([undefined, false, true])(
+    'round-trips ordering (%s)',
+    (enforceOrder) => {
+      const policy = { admins: [token], rules: { ...rules, enforceOrder } }
+      const expected = {
+        ...policy,
+        rules: { ...policy.rules, enforceOrder: enforceOrder ?? false },
+      }
+      expect(FundingPolicy.decode(FundingPolicy.encode(policy.rules))).toEqual(
+        expected.rules,
+      )
+      expect(FundingPolicy.fromTuple(FundingPolicy.toTuple(policy))).toEqual(
+        expected,
+      )
+      expect(FundingPolicy.fromRpc(FundingPolicy.toRpc(policy))).toEqual(policy)
+      const authorization = {
+        address: target,
+        chainId: 1n,
+        fundingPolicy: policy,
+        type: 'secp256k1' as const,
+      }
+      expect(
+        KeyAuthorization.deserialize(KeyAuthorization.serialize(authorization)),
+      ).toEqual({
+        ...authorization,
+        fundingPolicy: expected,
+      })
+    },
+  )
+
+  test('omitted ordering encodes identically to false', () => {
+    const { enforceOrder: _, ...unordered } = rules
+    expect(FundingPolicy.encode(unordered)).toBe(FundingPolicy.encode(rules))
+    expect(FundingPolicy.hash(unordered)).toBe(FundingPolicy.hash(rules))
+    expect(
+      FundingPolicy.toTuple({ admins: [token], rules: unordered }),
+    ).toEqual(FundingPolicy.toTuple({ admins: [token], rules }))
+  })
+
+  test('ordering changes the commitment and authorization signature', () => {
+    const ordered = { ...rules, enforceOrder: true }
+    expect(FundingPolicy.hash(ordered)).not.toBe(FundingPolicy.hash(rules))
+    const authorization = {
+      address: target,
+      chainId: 1n,
+      fundingPolicy: { admins: [token], rules },
+      type: 'secp256k1' as const,
+    }
+    expect(KeyAuthorization.getSignPayload(authorization)).not.toBe(
+      KeyAuthorization.getSignPayload({
+        ...authorization,
+        fundingPolicy: { admins: [token], rules: ordered },
+      }),
+    )
+  })
+
+  test('uses the canonical rules wire layout', () => {
+    for (const enforceOrder of [false, true]) {
+      const empty = { enforceOrder, maxSlippageBps: 0, sources: {} }
+      const abi = `0x${[
+        '20', // Dynamic tuple offset.
+        '00', // Slippage.
+        '60', // Routes offset within the tuple.
+        enforceOrder ? '01' : '00',
+        '00', // Empty routes.
+      ]
+        .map((word) => word.padStart(64, '0'))
+        .join('')}`
+      expect(FundingPolicy.encode(empty)).toBe(abi)
+      const tuple = FundingPolicy.toTuple({ admins: [token], rules: empty })
+      if (typeof tuple === 'string')
+        throw new Error('Expected an inline policy.')
+      expect(Rlp.fromHex(tuple[1])).toBe(
+        enforceOrder ? '0xc380c001' : '0xc380c080',
+      )
+    }
+  })
+
+  test('rejects invalid and missing ordering flags', () => {
+    for (const enforceOrder of [0, 1, 'false', null])
+      expect(() =>
+        FundingPolicy.encode({ ...rules, enforceOrder } as never),
+      ).toThrowErrorMatchingInlineSnapshot(
+        `[FundingPolicy.InvalidPolicyError: Ordering enforcement must be a boolean.]`,
+      )
+    for (const suffix of [[], ['0x00'], ['0x02'], ['0x0001']])
+      expect(() =>
+        FundingPolicy.fromTuple([[token], ['0x', [], ...suffix]] as never),
+      ).toThrow()
+  })
+})