ox 1.7.1 → 1.7.2

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

@@ -0,0 +1,42 @@
+import { expectTypeOf, test } from 'vp/test'
+import * as MultisigWitness from './MultisigWitness.js'
+
+const rpc = {
+  account: '0x2222222222222222222222222222222222222222',
+  approvals: [
+    {
+      owner: '0x1111111111111111111111111111111111111111',
+      type: 'primitive',
+    },
+  ],
+  config: {
+    owners: [
+      {
+        owner: '0x1111111111111111111111111111111111111111',
+        weight: 1,
+      },
+    ],
+    salt: '0x0000000000000000000000000000000000000000000000000000000000000000',
+    threshold: 1,
+    version: 0,
+  },
+} as const satisfies MultisigWitness.Rpc
+
+test('fromRpc returns a domain witness', () => {
+  const witness = MultisigWitness.fromRpc(rpc)
+
+  expectTypeOf(witness).toEqualTypeOf<MultisigWitness.MultisigWitness>()
+  expectTypeOf(witness.config.version).toEqualTypeOf<bigint>()
+})
+
+test('RPC witnesses use numeric configuration versions', () => {
+  expectTypeOf<
+    MultisigWitness.Rpc['config']['version']
+  >().toEqualTypeOf<number>()
+})
+
+test('toRpc returns an RPC witness', () => {
+  expectTypeOf(
+    MultisigWitness.toRpc(MultisigWitness.fromRpc(rpc)),
+  ).toEqualTypeOf<MultisigWitness.Rpc>()
+})

package/src/tempo/MultisigWitness.test.ts

@@ -0,0 +1,288 @@
+import { MultisigWitness } from 'ox/tempo'
+import { describe, expect, test } from 'vp/test'
+
+const rpc = {
+  account: '0xcccccccccccccccccccccccccccccccccccccccc',
+  approvals: [
+    {
+      keyData: '0x0102030405',
+      keyType: 'webAuthn',
+      owner: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+      type: 'primitive',
+    },
+    {
+      type: 'multisig',
+      witness: {
+        account: '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+        approvals: [
+          {
+            keyData: '0x010203040506',
+            keyType: 'secp256k1',
+            owner: '0xdddddddddddddddddddddddddddddddddddddddd',
+          },
+          {
+            owner: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
+          },
+        ],
+        config: {
+          owners: [
+            {
+              owner: '0xdddddddddddddddddddddddddddddddddddddddd',
+              weight: 1,
+            },
+            {
+              owner: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee',
+              weight: 1,
+            },
+          ],
+          salt: '0x2222222222222222222222222222222222222222222222222222222222222222',
+          threshold: 2,
+          version: 2,
+        },
+      },
+    },
+  ],
+  config: {
+    owners: [
+      {
+        owner: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+        weight: 1,
+      },
+      {
+        owner: '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+        weight: 1,
+      },
+    ],
+    salt: '0x1111111111111111111111111111111111111111111111111111111111111111',
+    threshold: 2,
+    version: 1,
+  },
+} as const satisfies MultisigWitness.Rpc
+
+describe('fromRpc', () => {
+  test('behavior: converts numeric configuration versions to bigint', () => {
+    expect(MultisigWitness.fromRpc(rpc)).toMatchInlineSnapshot(`
+      {
+        "account": "0xcccccccccccccccccccccccccccccccccccccccc",
+        "approvals": [
+          {
+            "keyData": "0x0102030405",
+            "keyType": "webAuthn",
+            "owner": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+            "type": "primitive",
+          },
+          {
+            "type": "multisig",
+            "witness": {
+              "account": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+              "approvals": [
+                {
+                  "keyData": "0x010203040506",
+                  "keyType": "secp256k1",
+                  "owner": "0xdddddddddddddddddddddddddddddddddddddddd",
+                },
+                {
+                  "owner": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+                },
+              ],
+              "config": {
+                "owners": [
+                  {
+                    "owner": "0xdddddddddddddddddddddddddddddddddddddddd",
+                    "weight": 1,
+                  },
+                  {
+                    "owner": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+                    "weight": 1,
+                  },
+                ],
+                "salt": "0x2222222222222222222222222222222222222222222222222222222222222222",
+                "threshold": 2,
+                "version": 2n,
+              },
+            },
+          },
+        ],
+        "config": {
+          "owners": [
+            {
+              "owner": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+              "weight": 1,
+            },
+            {
+              "owner": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+              "weight": 1,
+            },
+          ],
+          "salt": "0x1111111111111111111111111111111111111111111111111111111111111111",
+          "threshold": 2,
+          "version": 1n,
+        },
+      }
+    `)
+  })
+
+  test('error: rejects unsafe numeric configuration versions', () => {
+    expect(() =>
+      MultisigWitness.fromRpc({
+        ...rpc,
+        config: {
+          ...rpc.config,
+          version: Number.MAX_SAFE_INTEGER + 1,
+        },
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[MultisigConfig.InvalidConfigError: Invalid native multisig config: version must be an unsigned 64-bit integer.]`,
+    )
+  })
+
+  test('error: rejects excess root approvals', () => {
+    expect(() =>
+      MultisigWitness.fromRpc({
+        ...rpc,
+        approvals: Array.from({ length: 9 }, () => rpc.approvals[0]),
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[MultisigWitness.InvalidWitnessError: Invalid multisig witness: approval count exceeds 8.]`,
+    )
+  })
+
+  test('error: rejects excess nested approvals', () => {
+    expect(() =>
+      MultisigWitness.fromRpc({
+        ...rpc,
+        approvals: [
+          {
+            ...rpc.approvals[1],
+            witness: {
+              ...rpc.approvals[1].witness,
+              approvals: Array.from(
+                { length: 9 },
+                () => rpc.approvals[1].witness.approvals[0],
+              ),
+            },
+          },
+        ],
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[MultisigWitness.InvalidWitnessError: Invalid multisig witness: approval count exceeds 8.]`,
+    )
+  })
+})
+
+describe('toRpc', () => {
+  test('behavior: converts bigint configuration versions to numbers', () => {
+    expect(MultisigWitness.toRpc(MultisigWitness.fromRpc(rpc)))
+      .toMatchInlineSnapshot(`
+      {
+        "account": "0xcccccccccccccccccccccccccccccccccccccccc",
+        "approvals": [
+          {
+            "keyData": "0x0005",
+            "keyType": "webAuthn",
+            "owner": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+            "type": "primitive",
+          },
+          {
+            "type": "multisig",
+            "witness": {
+              "account": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+              "approvals": [
+                {
+                  "keyData": "0x0006",
+                  "keyType": "secp256k1",
+                  "owner": "0xdddddddddddddddddddddddddddddddddddddddd",
+                },
+                {
+                  "owner": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+                },
+              ],
+              "config": {
+                "owners": [
+                  {
+                    "owner": "0xdddddddddddddddddddddddddddddddddddddddd",
+                    "weight": 1,
+                  },
+                  {
+                    "owner": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+                    "weight": 1,
+                  },
+                ],
+                "salt": "0x2222222222222222222222222222222222222222222222222222222222222222",
+                "threshold": 2,
+                "version": 2,
+              },
+            },
+          },
+        ],
+        "config": {
+          "owners": [
+            {
+              "owner": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+              "weight": 1,
+            },
+            {
+              "owner": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+              "weight": 1,
+            },
+          ],
+          "salt": "0x1111111111111111111111111111111111111111111111111111111111111111",
+          "threshold": 2,
+          "version": 1,
+        },
+      }
+    `)
+  })
+
+  test('error: rejects versions that JSON cannot represent exactly', () => {
+    const witness = MultisigWitness.fromRpc(rpc)
+    expect(() =>
+      MultisigWitness.toRpc({
+        ...witness,
+        config: {
+          ...witness.config,
+          version: BigInt(Number.MAX_SAFE_INTEGER) + 1n,
+        },
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[Hex.IntegerOutOfRangeError: Number \`9007199254740992\` is not in safe unsigned integer range (\`0\` to \`9007199254740991\`)]`,
+    )
+  })
+
+  test('error: rejects excess root approvals', () => {
+    const witness = MultisigWitness.fromRpc(rpc)
+    expect(() =>
+      MultisigWitness.toRpc({
+        ...witness,
+        approvals: Array.from({ length: 9 }, () => witness.approvals[0]!),
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[MultisigWitness.InvalidWitnessError: Invalid multisig witness: approval count exceeds 8.]`,
+    )
+  })
+
+  test('error: rejects excess nested approvals', () => {
+    const witness = MultisigWitness.fromRpc(rpc)
+    const nested = witness.approvals[1]!
+    if (nested.type !== 'multisig') throw new Error('unreachable')
+    expect(() =>
+      MultisigWitness.toRpc({
+        ...witness,
+        approvals: [
+          {
+            ...nested,
+            witness: {
+              ...nested.witness,
+              approvals: Array.from(
+                { length: 9 },
+                () => nested.witness.approvals[0]!,
+              ),
+            },
+          },
+        ],
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(
+      `[MultisigWitness.InvalidWitnessError: Invalid multisig witness: approval count exceeds 8.]`,
+    )
+  })
+})

package/src/tempo/MultisigWitness.ts

@@ -0,0 +1,210 @@
+import type * 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 MultisigConfig from './MultisigConfig.js'
+import type * as SignatureEnvelope from './SignatureEnvelope.js'
+
+/** Native multisig owner approval used for RPC simulation. */
+export type Approval<versionType = bigint> =
+  | NestedApproval<versionType>
+  | PrimitiveApproval
+
+/** Native multisig witness used to construct an RPC simulation signature. */
+export type MultisigWitness<versionType = bigint> = Compute<{
+  /** Account authorized by this witness. */
+  account: Address.Address
+  /** Owner approvals to model. */
+  approvals: readonly Approval<versionType>[]
+  /** Complete applicable configuration. */
+  config: MultisigConfig.Config<versionType>
+}>
+
+/** Nested native multisig owner approval used for RPC simulation. */
+export type NestedApproval<versionType = bigint> = {
+  /** Approval type. */
+  type: 'multisig'
+  /** Depth-2 multisig witness. */
+  witness: NestedWitness<versionType>
+}
+
+/** Primitive approval in a depth-2 multisig simulation witness. */
+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 witness used for RPC simulation. */
+export type NestedWitness<versionType = bigint> = {
+  /** Nested multisig account. */
+  account: Address.Address
+  /** Primitive owner approvals to model. */
+  approvals: readonly NestedPrimitiveApproval[]
+  /** Complete applicable configuration. */
+  config: MultisigConfig.Config<versionType>
+}
+
+/** 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 witness. */
+export type Rpc = MultisigWitness<number>
+
+/**
+ * Converts a JSON-RPC multisig witness to its domain representation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { MultisigWitness } from 'ox/tempo'
+ *
+ * const witness = MultisigWitness.fromRpc(witnessRpc)
+ * ```
+ *
+ * @param witness - JSON-RPC multisig witness.
+ * @returns The multisig witness with bigint configuration versions.
+ */
+export function fromRpc(witness: Rpc): MultisigWitness {
+  const { account, approvals, config } = witness
+  assertApprovalCount(approvals)
+  return {
+    account,
+    approvals: approvals.map((approval) => {
+      if (approval.type === 'primitive') return approval
+      assertApprovalCount(approval.witness.approvals)
+      return {
+        type: 'multisig',
+        witness: {
+          account: approval.witness.account,
+          approvals: approval.witness.approvals,
+          config: MultisigConfig.from(approval.witness.config),
+        },
+      }
+    }),
+    config: MultisigConfig.from(config),
+  }
+}
+
+export declare namespace fromRpc {
+  /** Error type for `fromRpc`. */
+  export type ErrorType =
+    | InvalidWitnessError
+    | MultisigConfig.assert.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Converts a multisig witness to its JSON-RPC representation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { MultisigWitness } from 'ox/tempo'
+ *
+ * const witnessRpc = MultisigWitness.toRpc(witness)
+ * ```
+ *
+ * @param witness - Multisig witness.
+ * @returns The JSON-RPC multisig witness with numeric configuration versions.
+ */
+export function toRpc(witness: MultisigWitness): Rpc {
+  const { account, approvals, config } = witness
+  assertApprovalCount(approvals)
+  return {
+    account,
+    approvals: approvals.map((approval) => {
+      if (approval.type === 'primitive')
+        return {
+          ...approval,
+          ...(typeof approval.keyData !== 'undefined'
+            ? { keyData: shimKeyData(approval.keyData) }
+            : {}),
+        }
+      assertApprovalCount(approval.witness.approvals)
+      return {
+        type: 'multisig',
+        witness: {
+          account: approval.witness.account,
+          approvals: approval.witness.approvals.map((approval) => ({
+            ...approval,
+            ...(typeof approval.keyData !== 'undefined'
+              ? { keyData: shimKeyData(approval.keyData) }
+              : {}),
+          })),
+          config: configToRpc(approval.witness.config),
+        },
+      }
+    }),
+    config: configToRpc(config),
+  }
+}
+
+export declare namespace toRpc {
+  /** Error type for `toRpc`. */
+  export type ErrorType =
+    | Hex.fromNumber.ErrorType
+    | Hex.toNumber.ErrorType
+    | InvalidWitnessError
+    | MultisigConfig.assert.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/** @internal */
+function assertApprovalCount(approvals: readonly unknown[]) {
+  if (approvals.length > MultisigConfig.maxSignatures)
+    throw new InvalidWitnessError({
+      reason: `approval count exceeds ${MultisigConfig.maxSignatures}`,
+    })
+}
+
+/** @internal */
+function configToRpc(
+  config: MultisigConfig.Config,
+): MultisigConfig.Config<number> {
+  const value = MultisigConfig.from(config)
+  return {
+    ...value,
+    version: Hex.toNumber(Hex.fromNumber(value.version)),
+  }
+}
+
+/**
+ * Shims key data longer than 4 bytes into a 2-byte big-endian length hint.
+ * The node's gas estimator only accepts 1, 2, or 4-byte key data as a
+ * signature-size hint; anything else silently falls back to the default.
+ * @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 witness is invalid. */
+export class InvalidWitnessError extends Errors.BaseError {
+  override readonly name = 'MultisigWitness.InvalidWitnessError'
+  constructor(options: InvalidWitnessError.Options) {
+    super(`Invalid multisig witness: ${options.reason}.`)
+  }
+}
+
+export declare namespace InvalidWitnessError {
+  /** Error construction options. */
+  export type Options = {
+    /** Validation failure. */
+    reason: string
+  }
+}

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

@@ -0,0 +1,56 @@
+import type { Provider } from 'ox'
+import type {
+  KeyAuthorization,
+  MultisigOperation,
+  RpcSchemaTempo,
+} from 'ox/tempo'
+import { expectTypeOf, test } from 'vp/test'
+import type * as Hex from '../core/Hex.js'
+
+declare const provider: Provider.Provider<{ schema: RpcSchemaTempo.Multisig }>
+declare const hash: Hex.Hex
+declare const keyAuthorization: KeyAuthorization.Rpc
+declare const serializedTransaction: Hex.Hex
+declare const signature: Hex.Hex
+
+test('multisig provider methods', () => {
+  expectTypeOf(
+    provider.request({
+      method: 'multisig_approveRawTransaction',
+      params: [serializedTransaction],
+    }),
+  ).resolves.toEqualTypeOf<Hex.Hex>()
+
+  expectTypeOf(
+    provider.request({
+      method: 'multisig_approveRawTransactionSync',
+      params: [serializedTransaction],
+    }),
+  ).resolves.toEqualTypeOf<MultisigOperation.TransactionRpc>()
+
+  void provider.request({
+    method: 'multisig_approveRawTransactionSync',
+    params: [serializedTransaction, 30_000],
+  })
+
+  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_getOperation',
+      params: [hash],
+    }),
+  ).resolves.toEqualTypeOf<MultisigOperation.Rpc | null>()
+})

package/src/tempo/RpcSchemaTempo.ts

@@ -4,6 +4,8 @@ import type * as Hex from '../core/Hex.js'
 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 MultisigOperation from './MultisigOperation.js'
 import type * as TransactionRequest from './TransactionRequest.js'
 
 /**
@@ -53,3 +55,38 @@ export type Tempo = RpcSchema.From<{
     }
   }
 }>
+
+/** Union of all JSON-RPC methods for the `multisig_` namespace. */
+export type Multisig = RpcSchema.From<
+  | {
+      Request: {
+        method: 'multisig_approveRawTransaction'
+        params: [serializedTransaction: Hex.Hex]
+      }
+      ReturnType: Hex.Hex
+    }
+  | {
+      Request: {
+        method: 'multisig_approveRawTransactionSync'
+        params: [serializedTransaction: Hex.Hex, timeout?: number]
+      }
+      ReturnType: MultisigOperation.TransactionRpc
+    }
+  | {
+      Request: {
+        method: 'multisig_approveKeyAuthorization'
+        params: [
+          | { keyAuthorization: KeyAuthorization.Rpc }
+          | { hash: Hex.Hex; signature: Hex.Hex },
+        ]
+      }
+      ReturnType: MultisigOperation.KeyAuthorizationRpc
+    }
+  | {
+      Request: {
+        method: 'multisig_getOperation'
+        params: [hash: Hex.Hex]
+      }
+      ReturnType: MultisigOperation.Rpc | null
+    }
+>