ox 0.14.42 → 0.14.44

package/tempo/MultisigSimulation.test.ts

@@ -0,0 +1,284 @@
+import { MultisigConfig, MultisigSimulation } from 'ox/tempo'
+import { describe, expect, test } from 'vitest'
+
+const config =
+  '0xf852a011111111111111111111111111111111111111111111111111111111111111118002eed694111111111111111111111111111111111111111101d694bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb01' as const
+const nestedConfig =
+  '0xf83ba022222222222222222222222222222222222222222222222222222222222222220101d7d694222222222222222222222222222222222222222201' as const
+const rpc = {
+  account: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+  approvals: [
+    {
+      keyData: '0x0102030405',
+      keyType: 'webAuthn',
+      owner: '0x1111111111111111111111111111111111111111',
+      type: 'primitive',
+    },
+    {
+      spec: {
+        account: '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+        approvals: [
+          {
+            keyData: '0x010203040506',
+            keyType: 'secp256k1',
+            owner: '0x2222222222222222222222222222222222222222',
+          },
+        ],
+        config: nestedConfig,
+      },
+      type: 'multisig',
+    },
+  ],
+  config,
+} as const satisfies MultisigSimulation.Rpc
+
+describe('fromRpc', () => {
+  test('behavior: decodes root and nested configurations', () => {
+    expect(MultisigSimulation.fromRpc(rpc)).toMatchInlineSnapshot(`
+      {
+        "account": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "approvals": [
+          {
+            "keyData": "0x0102030405",
+            "keyType": "webAuthn",
+            "owner": "0x1111111111111111111111111111111111111111",
+            "type": "primitive",
+          },
+          {
+            "spec": {
+              "account": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+              "approvals": [
+                {
+                  "keyData": "0x010203040506",
+                  "keyType": "secp256k1",
+                  "owner": "0x2222222222222222222222222222222222222222",
+                },
+              ],
+              "config": {
+                "owners": [
+                  {
+                    "owner": "0x2222222222222222222222222222222222222222",
+                    "weight": 1,
+                  },
+                ],
+                "salt": "0x2222222222222222222222222222222222222222222222222222222222222222",
+                "threshold": 1,
+                "version": 1n,
+              },
+            },
+            "type": "multisig",
+          },
+        ],
+        "config": {
+          "owners": [
+            {
+              "owner": "0x1111111111111111111111111111111111111111",
+              "weight": 1,
+            },
+            {
+              "owner": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+              "weight": 1,
+            },
+          ],
+          "salt": "0x1111111111111111111111111111111111111111111111111111111111111111",
+          "threshold": 2,
+          "version": 0n,
+        },
+      }
+    `)
+  })
+
+  test('behavior: preserves the maximum uint64 configuration version', () => {
+    const config =
+      '0xf843a0000000000000000000000000000000000000000000000000000000000000000088ffffffffffffffff01d7d694111111111111111111111111111111111111111101' as const
+
+    expect(
+      MultisigSimulation.fromRpc({ ...rpc, approvals: [], config }).config
+        .version,
+    ).toMatchInlineSnapshot(`18446744073709551615n`)
+  })
+
+  test('error: rejects excess root approvals', () => {
+    expect(() =>
+      MultisigSimulation.fromRpc({
+        ...rpc,
+        approvals: Array.from({ length: 9 }, () => rpc.approvals[0]),
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[MultisigSimulation.InvalidSimulationError: Invalid multisig simulation: approval count exceeds 8.]`,
+    )
+  })
+
+  test('error: rejects excess nested approvals', () => {
+    expect(() =>
+      MultisigSimulation.fromRpc({
+        ...rpc,
+        approvals: [
+          {
+            ...rpc.approvals[1],
+            spec: {
+              ...rpc.approvals[1].spec,
+              approvals: Array.from(
+                { length: 9 },
+                () => rpc.approvals[1].spec.approvals[0],
+              ),
+            },
+          },
+        ],
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[MultisigSimulation.InvalidSimulationError: Invalid multisig simulation: approval count exceeds 8.]`,
+    )
+  })
+
+  test('error: rejects trailing configuration bytes', () => {
+    expect(() =>
+      MultisigSimulation.fromRpc({ ...rpc, config: `${config}00` }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[MultisigSimulation.InvalidSimulationError: Invalid multisig simulation: noncanonical config encoding.]`,
+    )
+  })
+
+  test('error: rejects malformed configuration RLP', () => {
+    expect(() =>
+      MultisigSimulation.fromRpc({ ...rpc, config: '0xf8' }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Cursor.PositionOutOfBoundsError: Position \`1\` is out of bounds (\`0 < position < 1\`).]`,
+    )
+  })
+
+  test('error: rejects a non-list configuration', () => {
+    expect(() =>
+      MultisigSimulation.fromRpc({ ...rpc, config: '0x01' }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[MultisigSimulation.InvalidSimulationError: Invalid multisig simulation: invalid config encoding.]`,
+    )
+  })
+
+  test('error: rejects noncanonical configuration integers', () => {
+    const noncanonical = config
+      .replace('0xf852', '0xf853')
+      .replace('118002', '11810002') as `0x${string}`
+
+    expect(() =>
+      MultisigSimulation.fromRpc({ ...rpc, config: noncanonical }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[MultisigSimulation.InvalidSimulationError: Invalid multisig simulation: invalid config encoding.]`,
+    )
+  })
+})
+
+describe('toRpc', () => {
+  test('behavior: encodes configurations and shims long key data', () => {
+    expect(
+      MultisigSimulation.toRpc(MultisigSimulation.fromRpc(rpc)),
+    ).toMatchInlineSnapshot(`
+      {
+        "account": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "approvals": [
+          {
+            "keyData": "0x0005",
+            "keyType": "webAuthn",
+            "owner": "0x1111111111111111111111111111111111111111",
+            "type": "primitive",
+          },
+          {
+            "spec": {
+              "account": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+              "approvals": [
+                {
+                  "keyData": "0x0006",
+                  "keyType": "secp256k1",
+                  "owner": "0x2222222222222222222222222222222222222222",
+                },
+              ],
+              "config": "${nestedConfig}",
+            },
+            "type": "multisig",
+          },
+        ],
+        "config": "${config}",
+      }
+    `)
+  })
+
+  test('behavior: preserves short key data', () => {
+    const spec = MultisigSimulation.fromRpc({
+      ...rpc,
+      approvals: [{ ...rpc.approvals[0], keyData: '0x0102' }],
+    })
+
+    expect(MultisigSimulation.toRpc(spec).approvals).toMatchInlineSnapshot(`
+      [
+        {
+          "keyData": "0x0102",
+          "keyType": "webAuthn",
+          "owner": "0x1111111111111111111111111111111111111111",
+          "type": "primitive",
+        },
+      ]
+    `)
+  })
+
+  test('behavior: encodes the maximum uint64 configuration version', () => {
+    const spec = MultisigSimulation.fromRpc(rpc)
+
+    expect(
+      MultisigSimulation.toRpc({
+        ...spec,
+        approvals: [],
+        config: MultisigConfig.from({
+          owners: [
+            {
+              owner: '0x1111111111111111111111111111111111111111',
+              weight: 1,
+            },
+          ],
+          threshold: 1,
+          version: MultisigConfig.maxVersion,
+        }),
+      }).config,
+    ).toMatchInlineSnapshot(
+      `"0xf843a0000000000000000000000000000000000000000000000000000000000000000088ffffffffffffffff01d7d694111111111111111111111111111111111111111101"`,
+    )
+  })
+
+  test('error: rejects excess root approvals', () => {
+    const spec = MultisigSimulation.fromRpc(rpc)
+
+    expect(() =>
+      MultisigSimulation.toRpc({
+        ...spec,
+        approvals: Array.from({ length: 9 }, () => spec.approvals[0]!),
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[MultisigSimulation.InvalidSimulationError: Invalid multisig simulation: approval count exceeds 8.]`,
+    )
+  })
+
+  test('error: rejects excess nested approvals', () => {
+    const spec = MultisigSimulation.fromRpc(rpc)
+    const nested = spec.approvals[1]!
+    if (nested.type !== 'multisig') throw new Error('unreachable')
+
+    expect(() =>
+      MultisigSimulation.toRpc({
+        ...spec,
+        approvals: [
+          {
+            ...nested,
+            spec: {
+              ...nested.spec,
+              approvals: Array.from(
+                { length: 9 },
+                () => nested.spec.approvals[0]!,
+              ),
+            },
+          },
+        ],
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[MultisigSimulation.InvalidSimulationError: Invalid multisig simulation: approval count exceeds 8.]`,
+    )
+  })
+})

package/tempo/MultisigSimulation.ts

@@ -0,0 +1,266 @@
+import * as Address from '../core/Address.js'
+import * as Errors from '../core/Errors.js'
+import * as Hex from '../core/Hex.js'
+import type { Compute } from '../core/internal/types.js'
+import * as Rlp from '../core/Rlp.js'
+import * as MultisigConfig from './MultisigConfig.js'
+import type * as SignatureEnvelope from './SignatureEnvelope.js'
+
+/** Native multisig owner approval used for RPC simulation. */
+export type Approval = NestedApproval | PrimitiveApproval
+
+/** JSON-RPC native multisig owner approval used for RPC simulation. */
+export type ApprovalRpc = NestedApprovalRpc | PrimitiveApproval
+
+/** Nested native multisig owner approval used for RPC simulation. */
+export type NestedApproval = {
+  /** Depth-2 multisig simulation spec. */
+  spec: NestedSpec
+  /** Approval type. */
+  type: 'multisig'
+}
+
+/** JSON-RPC nested native multisig owner approval used for RPC simulation. */
+export type NestedApprovalRpc = {
+  /** Depth-2 multisig simulation spec. */
+  spec: NestedSpecRpc
+  /** Approval type. */
+  type: 'multisig'
+}
+
+/** Primitive approval in a depth-2 multisig simulation spec. */
+export type NestedPrimitiveApproval = {
+  /** Optional signature-specific gas-estimation data. */
+  keyData?: Hex.Hex | undefined
+  /** Signature type to model. Omission uses a maximum-size WebAuthn signature. */
+  keyType?: SignatureEnvelope.Type | undefined
+  /** Configured owner address. */
+  owner: Address.Address
+}
+
+/** Depth-2 native multisig spec used for RPC simulation. */
+export type NestedSpec = {
+  /** Nested multisig account. */
+  account: Address.Address
+  /** Primitive owner approvals to model. */
+  approvals: readonly NestedPrimitiveApproval[]
+  /** Complete applicable configuration. */
+  config: MultisigConfig.Config
+}
+
+/** JSON-RPC depth-2 native multisig spec used for RPC simulation. */
+export type NestedSpecRpc = {
+  /** Nested multisig account. */
+  account: Address.Address
+  /** Primitive owner approvals to model. */
+  approvals: readonly NestedPrimitiveApproval[]
+  /** Canonical RLP-encoded applicable configuration. */
+  config: Hex.Hex
+}
+
+/** Primitive owner approval used for RPC simulation. */
+export type PrimitiveApproval = {
+  /** Optional signature-specific gas-estimation data. */
+  keyData?: Hex.Hex | undefined
+  /** Signature type to model. Omission uses a maximum-size WebAuthn signature. */
+  keyType?: SignatureEnvelope.Type | undefined
+  /** Configured owner address. */
+  owner: Address.Address
+  /** Approval type. */
+  type: 'primitive'
+}
+
+/** JSON-RPC representation of a native multisig simulation spec. */
+export type Rpc = Compute<{
+  /** Account authorized by this spec. */
+  account: Address.Address
+  /** Owner approvals to model. */
+  approvals: readonly ApprovalRpc[]
+  /** Canonical RLP-encoded applicable configuration. */
+  config: Hex.Hex
+}>
+
+/** Native multisig spec used to construct an RPC simulation signature. */
+export type Spec = Compute<{
+  /** Account authorized by this spec. */
+  account: Address.Address
+  /** Owner approvals to model. */
+  approvals: readonly Approval[]
+  /** Complete applicable configuration. */
+  config: MultisigConfig.Config
+}>
+
+/**
+ * Converts a JSON-RPC multisig simulation spec to its domain representation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { MultisigSimulation } from 'ox/tempo'
+ *
+ * const spec = MultisigSimulation.fromRpc(specRpc)
+ * ```
+ *
+ * @param spec - JSON-RPC multisig simulation spec.
+ * @returns The multisig simulation spec with decoded configurations.
+ */
+export function fromRpc(spec: Rpc): Spec {
+  const { account, approvals, config } = spec
+  assertApprovalCount(approvals)
+  return {
+    account,
+    approvals: approvals.map((approval) => {
+      if (approval.type === 'primitive') return approval
+      assertApprovalCount(approval.spec.approvals)
+      return {
+        spec: {
+          account: approval.spec.account,
+          approvals: approval.spec.approvals,
+          config: deserializeConfig(approval.spec.config),
+        },
+        type: 'multisig',
+      }
+    }),
+    config: deserializeConfig(config),
+  }
+}
+
+export declare namespace fromRpc {
+  /** Error type for `fromRpc`. */
+  export type ErrorType =
+    | Hex.isEqual.ErrorType
+    | InvalidSimulationError
+    | MultisigConfig.assert.ErrorType
+    | Rlp.fromHex.ErrorType
+    | Rlp.toHex.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Converts a multisig simulation spec to its JSON-RPC representation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { MultisigSimulation } from 'ox/tempo'
+ *
+ * const specRpc = MultisigSimulation.toRpc(spec)
+ * ```
+ *
+ * @param spec - Multisig simulation spec.
+ * @returns The JSON-RPC multisig simulation spec with encoded configurations.
+ */
+export function toRpc(spec: Spec): Rpc {
+  const { account, approvals, config } = spec
+  assertApprovalCount(approvals)
+  return {
+    account,
+    approvals: approvals.map((approval) => {
+      if (approval.type === 'primitive')
+        return {
+          ...approval,
+          ...(typeof approval.keyData !== 'undefined'
+            ? { keyData: shimKeyData(approval.keyData) }
+            : {}),
+        }
+      assertApprovalCount(approval.spec.approvals)
+      return {
+        spec: {
+          account: approval.spec.account,
+          approvals: approval.spec.approvals.map((approval) => ({
+            ...approval,
+            ...(typeof approval.keyData !== 'undefined'
+              ? { keyData: shimKeyData(approval.keyData) }
+              : {}),
+          })),
+          config: serializeConfig(approval.spec.config),
+        },
+        type: 'multisig',
+      }
+    }),
+    config: serializeConfig(config),
+  }
+}
+
+export declare namespace toRpc {
+  /** Error type for `toRpc`. */
+  export type ErrorType =
+    | Hex.fromNumber.ErrorType
+    | InvalidSimulationError
+    | MultisigConfig.assert.ErrorType
+    | Rlp.fromHex.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/** @internal */
+function assertApprovalCount(approvals: readonly unknown[]) {
+  if (approvals.length > MultisigConfig.maxSignatures)
+    throw new InvalidSimulationError({
+      reason: `approval count exceeds ${MultisigConfig.maxSignatures}`,
+    })
+}
+
+/** @internal */
+function deserializeConfig(config: Hex.Hex): MultisigConfig.Config {
+  const tuple = Rlp.toHex(config)
+  if (!Array.isArray(tuple) || tuple.length !== 4)
+    throw new InvalidSimulationError({ reason: 'invalid config encoding' })
+  const [salt, version, threshold, owners] = tuple
+  if (
+    Array.isArray(salt) ||
+    Hex.size(salt) !== 32 ||
+    Array.isArray(version) ||
+    Hex.size(version) > 8 ||
+    (version !== '0x' && Hex.slice(version, 0, 1) === '0x00') ||
+    Array.isArray(threshold) ||
+    Hex.size(threshold) > 1 ||
+    !Array.isArray(owners) ||
+    owners.some(
+      (owner) =>
+        !Array.isArray(owner) ||
+        owner.length !== 2 ||
+        owner.some(Array.isArray) ||
+        !Address.validate(owner[0]) ||
+        Hex.size(owner[1] as Hex.Hex) > 1,
+    )
+  )
+    throw new InvalidSimulationError({ reason: 'invalid config encoding' })
+  const value = MultisigConfig.fromTuple(
+    tuple as unknown as MultisigConfig.Tuple,
+  )
+  MultisigConfig.assert(value)
+  if (!Hex.isEqual(config, serializeConfig(value)))
+    throw new InvalidSimulationError({ reason: 'noncanonical config encoding' })
+  return value
+}
+
+/** @internal */
+function serializeConfig(config: MultisigConfig.Input): Hex.Hex {
+  return Rlp.fromHex(MultisigConfig.toTuple(config))
+}
+
+/**
+ * Shims long key data into the length hint accepted by Tempo's gas estimator.
+ * @internal
+ */
+function shimKeyData(data: Hex.Hex): Hex.Hex {
+  const size = Hex.size(data)
+  if (size <= 4) return data
+  return Hex.fromNumber(size, { size: 2 })
+}
+
+/** Thrown when a native multisig simulation spec is invalid. */
+export class InvalidSimulationError extends Errors.BaseError {
+  override readonly name = 'MultisigSimulation.InvalidSimulationError'
+  constructor(options: InvalidSimulationError.Options) {
+    super(`Invalid multisig simulation: ${options.reason}.`)
+  }
+}
+
+export declare namespace InvalidSimulationError {
+  /** Error construction options. */
+  export type Options = {
+    /** Validation failure. */
+    reason: string
+  }
+}

package/tempo/RpcSchemaTempo.test-d.ts

@@ -3,7 +3,7 @@ import type {
   KeyAuthorization,
   MultisigConfig,
   MultisigOperation,
-  MultisigWitness,
+  MultisigSimulation,
   RpcSchemaTempo,
 } from 'ox/tempo'
 import { expectTypeOf, test } from 'vitest'
@@ -17,7 +17,7 @@ declare const tempoProvider: Provider.Provider<{
 declare const address: Address.Address
 declare const hash: Hex.Hex
 declare const keyAuthorization: KeyAuthorization.Rpc
-declare const multisigWitness: MultisigWitness.Rpc
+declare const multisigSimulation: MultisigSimulation.Rpc
 declare const serializedTransaction: Hex.Hex
 declare const signature: Hex.Hex
 
@@ -70,7 +70,7 @@ test('multisig provider methods', () => {
   ).resolves.toEqualTypeOf<MultisigOperation.Rpc | null>()
 })
 
-test('tempo simulation accepts multisig witnesses', () => {
+test('tempo simulation accepts multisig specs', () => {
   tempoProvider.request({
     method: 'tempo_simulateV1',
     params: [
@@ -79,7 +79,7 @@ test('tempo simulation accepts multisig witnesses', () => {
           {
             calls: [
               {
-                multisigWitness,
+                multisigSimulation,
               },
             ],
           },

package/tempo/SignatureEnvelope.test-d.ts

@@ -34,20 +34,10 @@ test('toRpc preserves the signature type', () => {
   ).toEqualTypeOf<SignatureEnvelope.Secp256k1Rpc>()
 })
 
-test('MultisigRpc carries one complete witness shape', () => {
-  const rpc = {
-    account: '0x1111111111111111111111111111111111111111',
-    config: { ...config, version: 0 },
-    signatures: [signatureRpc],
-  } as const satisfies SignatureEnvelope.MultisigRpc
+test('MultisigRpc contains an untagged serialized multisig signature', () => {
+  const rpc = '0xf8' as const satisfies SignatureEnvelope.MultisigRpc
 
-  expectTypeOf(rpc.config).toMatchTypeOf<MultisigConfig.Config<number>>()
-  expectTypeOf(rpc.signatures).toMatchTypeOf<
-    readonly SignatureEnvelope.SignatureEnvelopeRpc[]
-  >()
-  expectTypeOf<
-    SignatureEnvelope.GetType<typeof rpc>
-  >().toEqualTypeOf<'multisig'>()
+  expectTypeOf(rpc).toMatchTypeOf<`0x${string}`>()
 })
 
 test('from derives an initial account', () => {
@@ -75,40 +65,14 @@ test('from requires an account for a current config', () => {
   expectTypeOf(multisig).toMatchTypeOf<SignatureEnvelope.Multisig>()
 })
 
-test('MultisigRpc rejects old witness shapes', () => {
-  const accountOnly = {
-    account: '0x1111111111111111111111111111111111111111',
-    signatures: [signatureRpc],
-  } as const
-  // @ts-expect-error Multisig RPC signatures require config.
-  const accountOnlyRpc: SignatureEnvelope.MultisigRpc = accountOnly
-
-  const init = {
-    init: config,
-    signatures: [signatureRpc],
-  } as const
-  // @ts-expect-error Multisig RPC signatures no longer accept init.
-  const initRpc: SignatureEnvelope.MultisigRpc = init
-
-  const serialized = {
-    account: '0x1111111111111111111111111111111111111111',
-    config: { ...config, version: 0 },
-    signatures: ['0x1234'],
-  } as const
-  // @ts-expect-error Owner approvals use structured RPC envelopes.
-  const serializedRpc: SignatureEnvelope.MultisigRpc = serialized
-
-  const tagged = {
+test('MultisigRpc rejects structured signatures', () => {
+  const structured = {
     account: '0x1111111111111111111111111111111111111111',
     config: { ...config, version: 0 },
     signatures: [signatureRpc],
-    type: 'multisig',
   } as const
-  // @ts-expect-error Multisig RPC signatures are untagged.
-  const taggedRpc: SignatureEnvelope.MultisigRpc = tagged
+  // @ts-expect-error Multisig RPC signatures are serialized hex.
+  const rpc: SignatureEnvelope.MultisigRpc = structured
 
-  expectTypeOf(accountOnlyRpc).toEqualTypeOf<SignatureEnvelope.MultisigRpc>()
-  expectTypeOf(initRpc).toEqualTypeOf<SignatureEnvelope.MultisigRpc>()
-  expectTypeOf(serializedRpc).toEqualTypeOf<SignatureEnvelope.MultisigRpc>()
-  expectTypeOf(taggedRpc).toEqualTypeOf<SignatureEnvelope.MultisigRpc>()
+  expectTypeOf(rpc).toEqualTypeOf<SignatureEnvelope.MultisigRpc>()
 })