ox 1.7.2 → 1.7.5

package/src/tempo/MultisigSimulation.test.ts

@@ -0,0 +1,194 @@
+import { MultisigConfig, MultisigSimulation } from 'ox/tempo'
+import { describe, expect, test } from 'vp/test'
+
+const config =
+  '0xf852a011111111111111111111111111111111111111111111111111111111111111118002eed694111111111111111111111111111111111111111101d694bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb01' as const
+const rpc = {
+  approvals: [
+    {
+      keyType: 'webAuthn',
+      keyData: '0x0102030405',
+      owner: '0x1111111111111111111111111111111111111111',
+    },
+  ],
+  config,
+} as const satisfies MultisigSimulation.Rpc
+
+describe('fromRpc', () => {
+  test('behavior: decodes the configuration', () => {
+    expect(MultisigSimulation.fromRpc(rpc)).toMatchInlineSnapshot(`
+      {
+        "approvals": [
+          {
+            "keyData": "0x0102030405",
+            "keyType": "webAuthn",
+            "owner": "0x1111111111111111111111111111111111111111",
+          },
+        ],
+        "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 nested approvals', () => {
+    expect(() =>
+      MultisigSimulation.fromRpc({
+        ...rpc,
+        approvals: [{ type: 'multisig', spec: rpc }],
+      } as never),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[MultisigSimulation.InvalidSimulationError: Invalid multisig simulation: only untagged primitive owner approvals are allowed.]`,
+    )
+  })
+
+  test('error: rejects trailing configuration bytes', () => {
+    expect(() =>
+      MultisigSimulation.fromRpc({ ...rpc, config: `${config}00` }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Rlp.TrailingBytesError: RLP payload encodes a single item, but \`1\` trailing byte remains.]`,
+    )
+  })
+
+  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(`
+        {
+          "approvals": [
+            {
+              "keyData": "0x0005",
+              "keyType": "webAuthn",
+              "owner": "0x1111111111111111111111111111111111111111",
+            },
+          ],
+          "config": "0xf852a011111111111111111111111111111111111111111111111111111111111111118002eed694111111111111111111111111111111111111111101d694bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb01",
+        }
+      `)
+  })
+
+  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",
+        },
+      ]
+    `)
+  })
+
+  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 nested approvals', () => {
+    expect(() =>
+      MultisigSimulation.toRpc({
+        ...rpc,
+        approvals: [{ type: 'multisig', spec: rpc }],
+      } as never),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[MultisigSimulation.InvalidSimulationError: Invalid multisig simulation: only untagged primitive owner approvals are allowed.]`,
+    )
+  })
+})

package/src/tempo/MultisigSimulation.ts

@@ -0,0 +1,192 @@
+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 = PrimitiveApproval
+
+/** JSON-RPC native multisig owner approval used for RPC simulation. */
+export type ApprovalRpc = PrimitiveApproval
+
+/** 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
+}
+
+/** JSON-RPC representation of a native multisig simulation spec. */
+export type Rpc = Compute<{
+  /** 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<{
+  /** 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 { approvals, config } = spec
+  assertApprovals(approvals)
+  return { approvals, 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 { approvals, config } = spec
+  assertApprovals(approvals)
+  return {
+    approvals: approvals.map(({ keyData, keyType, owner }) => ({
+      ...(keyData !== undefined ? { keyData: shimKeyData(keyData) } : {}),
+      ...(keyType !== undefined ? { keyType } : {}),
+      owner,
+    })),
+    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 assertApprovals(approvals: readonly unknown[]) {
+  if (
+    approvals.some(
+      (approval) =>
+        typeof approval !== 'object' ||
+        approval === null ||
+        'spec' in approval ||
+        'type' in approval,
+    )
+  )
+    throw new InvalidSimulationError({
+      reason: 'only untagged primitive owner approvals are allowed',
+    })
+  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/src/tempo/RpcSchemaTempo.test-d.ts

@@ -1,19 +1,41 @@
 import type { Provider } from 'ox'
 import type {
   KeyAuthorization,
+  MultisigConfig,
   MultisigOperation,
+  MultisigSimulation,
   RpcSchemaTempo,
 } from 'ox/tempo'
 import { expectTypeOf, test } from 'vp/test'
+import type * as Address from '../core/Address.js'
 import type * as Hex from '../core/Hex.js'
 
 declare const provider: Provider.Provider<{ schema: RpcSchemaTempo.Multisig }>
+declare const tempoProvider: Provider.Provider<{
+  schema: RpcSchemaTempo.Tempo
+}>
+declare const address: Address.Address
 declare const hash: Hex.Hex
 declare const keyAuthorization: KeyAuthorization.Rpc
+declare const multisigSimulation: MultisigSimulation.Rpc
 declare const serializedTransaction: Hex.Hex
 declare const signature: Hex.Hex
 
 test('multisig provider methods', () => {
+  expectTypeOf(
+    provider.request({
+      method: 'multisig_approveKeyAuthorization',
+      params: [{ keyAuthorization }],
+    }),
+  ).resolves.toEqualTypeOf<MultisigOperation.KeyAuthorizationRpc>()
+
+  expectTypeOf(
+    provider.request({
+      method: 'multisig_approveKeyAuthorization',
+      params: [{ hash, signature }],
+    }),
+  ).resolves.toEqualTypeOf<MultisigOperation.KeyAuthorizationRpc>()
+
   expectTypeOf(
     provider.request({
       method: 'multisig_approveRawTransaction',
@@ -35,17 +57,10 @@ test('multisig provider methods', () => {
 
   expectTypeOf(
     provider.request({
-      method: 'multisig_approveKeyAuthorization',
-      params: [{ keyAuthorization }],
+      method: 'multisig_getConfig',
+      params: [{ address }],
     }),
-  ).resolves.toEqualTypeOf<MultisigOperation.KeyAuthorizationRpc>()
-
-  expectTypeOf(
-    provider.request({
-      method: 'multisig_approveKeyAuthorization',
-      params: [{ hash, signature }],
-    }),
-  ).resolves.toEqualTypeOf<MultisigOperation.KeyAuthorizationRpc>()
+  ).resolves.toEqualTypeOf<MultisigConfig.Rpc | null>()
 
   expectTypeOf(
     provider.request({
@@ -54,3 +69,23 @@ test('multisig provider methods', () => {
     }),
   ).resolves.toEqualTypeOf<MultisigOperation.Rpc | null>()
 })
+
+test('tempo simulation accepts multisig specs', () => {
+  void tempoProvider.request({
+    method: 'tempo_simulateV1',
+    params: [
+      {
+        blockStateCalls: [
+          {
+            calls: [
+              {
+                multisigSimulation,
+              },
+            ],
+          },
+        ],
+      },
+      'latest',
+    ],
+  })
+})

package/src/tempo/RpcSchemaTempo.ts

@@ -1,3 +1,4 @@
+import type * as Address from '../core/Address.js'
 import type * as Block from '../core/Block.js'
 import type * as BlockOverrides from '../core/BlockOverrides.js'
 import type * as Hex from '../core/Hex.js'
@@ -5,6 +6,7 @@ import type * as Log from '../core/Log.js'
 import type * as RpcSchema from '../core/RpcSchema.js'
 import type * as StateOverrides from '../core/StateOverrides.js'
 import type * as KeyAuthorization from './KeyAuthorization.js'
+import type * as MultisigConfig from './MultisigConfig.js'
 import type * as MultisigOperation from './MultisigOperation.js'
 import type * as TransactionRequest from './TransactionRequest.js'
 
@@ -58,6 +60,16 @@ export type Tempo = RpcSchema.From<{
 
 /** Union of all JSON-RPC methods for the `multisig_` namespace. */
 export type Multisig = RpcSchema.From<
+  | {
+      Request: {
+        method: 'multisig_approveKeyAuthorization'
+        params: [
+          | { keyAuthorization: KeyAuthorization.Rpc }
+          | { hash: Hex.Hex; signature: Hex.Hex },
+        ]
+      }
+      ReturnType: MultisigOperation.KeyAuthorizationRpc
+    }
   | {
       Request: {
         method: 'multisig_approveRawTransaction'
@@ -74,13 +86,10 @@ export type Multisig = RpcSchema.From<
     }
   | {
       Request: {
-        method: 'multisig_approveKeyAuthorization'
-        params: [
-          | { keyAuthorization: KeyAuthorization.Rpc }
-          | { hash: Hex.Hex; signature: Hex.Hex },
-        ]
+        method: 'multisig_getConfig'
+        params: [{ address: Address.Address }]
       }
-      ReturnType: MultisigOperation.KeyAuthorizationRpc
+      ReturnType: MultisigConfig.Rpc | null
     }
   | {
       Request: {

package/src/tempo/SignatureEnvelope.test-d.ts

@@ -1,114 +1,40 @@
 import { expectTypeOf, test } from 'vp/test'
-import * as MultisigConfig from './MultisigConfig.js'
+import type * as Hex from '../core/Hex.js'
 import * as SignatureEnvelope from './SignatureEnvelope.js'
 
-const signatureRpc = {
-  r: '0x01',
-  s: '0x02',
-  type: 'secp256k1',
-  yParity: '0x0',
-} as const satisfies SignatureEnvelope.SignatureEnvelopeRpc
-
-const signature = {
-  signature: {
-    r: '0x01',
-    s: '0x02',
-    yParity: 0,
+const primitive = SignatureEnvelope.from({ r: '0x01', s: '0x02', yParity: 0 })
+const envelope = SignatureEnvelope.from({
+  account: '0x2222222222222222222222222222222222222222',
+  config: {
+    threshold: 1,
+    version: 0n,
+    owners: [
+      { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
+    ],
   },
-  type: 'secp256k1',
-} as const satisfies SignatureEnvelope.Secp256k1
-
-const config = MultisigConfig.from({
-  owners: [
-    {
-      owner: '0x1111111111111111111111111111111111111111',
-      weight: 1,
-    },
-  ],
-  threshold: 1,
+  signatures: [primitive],
 })
 
-test('toRpc preserves the signature type', () => {
+test('preserves primitive and multisig RPC types', () => {
   expectTypeOf(
-    SignatureEnvelope.toRpc(signature),
+    SignatureEnvelope.toRpc(primitive),
   ).toEqualTypeOf<SignatureEnvelope.Secp256k1Rpc>()
-})
-
-test('MultisigRpc carries one complete witness shape', () => {
-  const rpc = {
-    account: '0x1111111111111111111111111111111111111111',
-    config: MultisigConfig.toRpc(config),
-    signatures: [signatureRpc],
-  } as const satisfies SignatureEnvelope.MultisigRpc
-
-  expectTypeOf(rpc.config).toMatchTypeOf<MultisigConfig.Rpc>()
-  expectTypeOf(rpc.signatures).toMatchTypeOf<
-    readonly SignatureEnvelope.SignatureEnvelopeRpc[]
-  >()
+  expectTypeOf(SignatureEnvelope.toRpc(envelope)).toEqualTypeOf<Hex.Hex>()
   expectTypeOf<
-    SignatureEnvelope.GetType<typeof rpc>
+    SignatureEnvelope.GetType<typeof envelope>
   >().toEqualTypeOf<'multisig'>()
+  expectTypeOf(envelope).toMatchTypeOf<SignatureEnvelope.Multisig>()
 })
 
-test('from derives an initial account', () => {
-  const multisig = SignatureEnvelope.from({
-    config,
-    signatures: [signature],
-  })
-
-  expectTypeOf(multisig).toMatchTypeOf<SignatureEnvelope.Multisig>()
-  expectTypeOf(multisig.config.version).toEqualTypeOf<bigint>()
-})
-
-test('from requires an account for a current config', () => {
-  // @ts-expect-error Current configurations require an explicit account.
-  SignatureEnvelope.from({
-    config: { ...config, version: 1 },
-    signatures: [signature],
-  })
-
-  const multisig = SignatureEnvelope.from({
-    account: '0x2222222222222222222222222222222222222222',
-    config: { ...config, version: 1 },
-    signatures: [signature],
-  })
-  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: MultisigConfig.toRpc(config),
-    signatures: ['0x1234'],
-  } as const
-  // @ts-expect-error Owner approvals use structured RPC envelopes.
-  const serializedRpc: SignatureEnvelope.MultisigRpc = serialized
-
-  const tagged = {
-    account: '0x1111111111111111111111111111111111111111',
-    config: MultisigConfig.toRpc(config),
-    signatures: [signatureRpc],
-    type: 'multisig',
-  } as const
-  // @ts-expect-error Multisig RPC signatures are untagged.
-  const taggedRpc: SignatureEnvelope.MultisigRpc = tagged
-
-  expectTypeOf(accountOnlyRpc).toEqualTypeOf<SignatureEnvelope.MultisigRpc>()
-  expectTypeOf(initRpc).toEqualTypeOf<SignatureEnvelope.MultisigRpc>()
-  expectTypeOf(serializedRpc).toEqualTypeOf<SignatureEnvelope.MultisigRpc>()
-  expectTypeOf(taggedRpc).toEqualTypeOf<SignatureEnvelope.MultisigRpc>()
+test('requires config and primitive approvals', () => {
+  // @ts-expect-error Every multisig signature carries its current config.
+  SignatureEnvelope.from({ account: envelope.account, signatures: [primitive] })
+  // @ts-expect-error Multisig owners cannot recursively approve with multisigs.
+  SignatureEnvelope.from({ ...envelope, signatures: [envelope] })
+  // @ts-expect-error Multisig RPC signatures are hex-encoded RLP.
+  const rpc: SignatureEnvelope.MultisigRpc = {
+    account: envelope.account,
+    signatures: [],
+  }
+  expectTypeOf(rpc).toEqualTypeOf<Hex.Hex>()
 })