ox 0.14.39 → 0.14.41

package/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(Number(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/tempo/RpcSchemaTempo.test-d.ts

@@ -2,14 +2,19 @@ import type { Provider } from 'ox'
 import type {
   KeyAuthorization,
   MultisigOperation,
+  MultisigWitness,
   RpcSchemaTempo,
 } from 'ox/tempo'
 import { expectTypeOf, test } from 'vitest'
 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 hash: Hex.Hex
 declare const keyAuthorization: KeyAuthorization.Rpc
+declare const multisigWitness: MultisigWitness.Rpc
 declare const serializedTransaction: Hex.Hex
 declare const signature: Hex.Hex
 
@@ -54,3 +59,23 @@ test('multisig provider methods', () => {
     }),
   ).resolves.toEqualTypeOf<MultisigOperation.Rpc | null>()
 })
+
+test('tempo simulation accepts multisig witnesses', () => {
+  tempoProvider.request({
+    method: 'tempo_simulateV1',
+    params: [
+      {
+        blockStateCalls: [
+          {
+            calls: [
+              {
+                multisigWitness,
+              },
+            ],
+          },
+        ],
+      },
+      'latest',
+    ],
+  })
+})

package/tempo/SignatureEnvelope.test-d.ts

@@ -37,11 +37,11 @@ test('toRpc preserves the signature type', () => {
 test('MultisigRpc carries one complete witness shape', () => {
   const rpc = {
     account: '0x1111111111111111111111111111111111111111',
-    config: MultisigConfig.toRpc(config),
+    config: { ...config, version: 0 },
     signatures: [signatureRpc],
   } as const satisfies SignatureEnvelope.MultisigRpc
 
-  expectTypeOf(rpc.config).toMatchTypeOf<MultisigConfig.Rpc>()
+  expectTypeOf(rpc.config).toMatchTypeOf<MultisigConfig.Config<number>>()
   expectTypeOf(rpc.signatures).toMatchTypeOf<
     readonly SignatureEnvelope.SignatureEnvelopeRpc[]
   >()
@@ -92,7 +92,7 @@ test('MultisigRpc rejects old witness shapes', () => {
 
   const serialized = {
     account: '0x1111111111111111111111111111111111111111',
-    config: MultisigConfig.toRpc(config),
+    config: { ...config, version: 0 },
     signatures: ['0x1234'],
   } as const
   // @ts-expect-error Owner approvals use structured RPC envelopes.
@@ -100,7 +100,7 @@ test('MultisigRpc rejects old witness shapes', () => {
 
   const tagged = {
     account: '0x1111111111111111111111111111111111111111',
-    config: MultisigConfig.toRpc(config),
+    config: { ...config, version: 0 },
     signatures: [signatureRpc],
     type: 'multisig',
   } as const

package/tempo/SignatureEnvelope.test.ts

@@ -3035,7 +3035,7 @@ describe('multisig', () => {
             ],
             "salt": "0x0000000000000000000000000000000000000000000000000000000000000000",
             "threshold": 1,
-            "version": "0x1",
+            "version": 1,
           },
           "signatures": [
             {
@@ -3057,7 +3057,7 @@ describe('multisig', () => {
             ],
             "salt": "0x0000000000000000000000000000000000000000000000000000000000000000",
             "threshold": 1,
-            "version": "0x0",
+            "version": 0,
           },
           "signatures": [
             {

package/tempo/SignatureEnvelope.ts

@@ -245,7 +245,7 @@ export type MultisigRpc = {
   /** Native multisig account address. */
   account: Address.Address
   /** Complete applicable multisig configuration witness. */
-  config: MultisigConfig.Rpc
+  config: MultisigConfig.Config<number>
   /** Structured owner approvals. */
   signatures: readonly SignatureEnvelopeRpc[]
   /** Multisig RPC signatures are untagged. */
@@ -1229,7 +1229,7 @@ export function fromRpc(envelope: SignatureEnvelopeRpc): SignatureEnvelope {
     const multisig = envelope as MultisigRpc
     const result = {
       account: multisig.account,
-      config: MultisigConfig.fromRpc(multisig.config),
+      config: MultisigConfig.from(multisig.config),
       signatures: multisig.signatures.map((signature) => fromRpc(signature)),
       type: 'multisig',
     } satisfies Multisig
@@ -1245,7 +1245,7 @@ export declare namespace fromRpc {
     | assert.ErrorType
     | CoercionError
     | InvalidSerializedError
-    | MultisigConfig.fromRpc.ErrorType
+    | MultisigConfig.assert.ErrorType
     | Signature.fromRpc.ErrorType
     | Errors.GlobalErrorType
 }
@@ -1614,7 +1614,10 @@ export function toRpc<const envelope extends toRpc.Input>(
     assert(multisig)
     return {
       account: multisig.account,
-      config: MultisigConfig.toRpc(multisig.config),
+      config: {
+        ...multisig.config,
+        version: Hex.toNumber(Hex.fromNumber(multisig.config.version)),
+      },
       signatures: multisig.signatures.map((signature) => toRpc(signature)),
     } as never
   }
@@ -1643,7 +1646,8 @@ export declare namespace toRpc {
   type ErrorType =
     | assert.ErrorType
     | CoercionError
-    | MultisigConfig.toRpc.ErrorType
+    | Hex.fromNumber.ErrorType
+    | Hex.toNumber.ErrorType
     | Signature.toRpc.ErrorType
     | Errors.GlobalErrorType
 }

package/tempo/TransactionRequest.test-d/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "types": "../../_types/tempo/TransactionRequest.test-d.d.ts",
+  "main": "../../_cjs/tempo/TransactionRequest.test-d.js",
+  "module": "../../_esm/tempo/TransactionRequest.test-d.js"
+}

package/tempo/TransactionRequest.test-d.ts

@@ -0,0 +1,24 @@
+import { expectTypeOf, test } from 'vitest'
+import type * as MultisigWitness from './MultisigWitness.js'
+import type * as TransactionRequest from './TransactionRequest.js'
+
+declare const request: TransactionRequest.TransactionRequest
+declare const rpc: TransactionRequest.Rpc
+
+test('transaction requests use domain multisig witnesses', () => {
+  expectTypeOf(request.multisigWitness?.config.version).toEqualTypeOf<
+    bigint | undefined
+  >()
+
+  const approval = request.multisigWitness?.approvals[0]
+  if (approval?.type === 'multisig')
+    expectTypeOf(approval.witness.approvals[0]?.keyType).toEqualTypeOf<
+      MultisigWitness.NestedPrimitiveApproval['keyType']
+    >()
+})
+
+test('RPC requests use numeric multisig config versions', () => {
+  expectTypeOf(rpc.multisigWitness?.config.version).toEqualTypeOf<
+    number | undefined
+  >()
+})

package/tempo/TransactionRequest.test.ts

@@ -1,6 +1,74 @@
-import { TransactionRequest } from 'ox/tempo'
+import { type MultisigWitness, TransactionRequest } from 'ox/tempo'
 import { describe, expect, test } from 'vitest'
 
+const multisigWitnessRpc = {
+  account: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+  approvals: [
+    {
+      keyType: 'secp256k1',
+      owner: '0x1111111111111111111111111111111111111111',
+      type: 'primitive',
+    },
+    {
+      type: 'multisig',
+      witness: {
+        account: '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+        approvals: [
+          {
+            keyData: '0x0578',
+            keyType: 'webAuthn',
+            owner: '0x2222222222222222222222222222222222222222',
+          },
+        ],
+        config: {
+          owners: [
+            {
+              owner: '0x2222222222222222222222222222222222222222',
+              weight: 1,
+            },
+          ],
+          salt: `0x${'22'.repeat(32)}`,
+          threshold: 1,
+          version: 1,
+        },
+      },
+    },
+  ],
+  config: {
+    owners: [
+      {
+        owner: '0x1111111111111111111111111111111111111111',
+        weight: 1,
+      },
+      {
+        owner: '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+        weight: 1,
+      },
+    ],
+    salt: `0x${'11'.repeat(32)}`,
+    threshold: 2,
+    version: 0,
+  },
+} as const satisfies MultisigWitness.Rpc
+
+const multisigWitness = {
+  ...multisigWitnessRpc,
+  approvals: [
+    multisigWitnessRpc.approvals[0],
+    {
+      ...multisigWitnessRpc.approvals[1],
+      witness: {
+        ...multisigWitnessRpc.approvals[1].witness,
+        config: {
+          ...multisigWitnessRpc.approvals[1].witness.config,
+          version: 1n,
+        },
+      },
+    },
+  ],
+  config: { ...multisigWitnessRpc.config, version: 0n },
+} as const satisfies MultisigWitness.MultisigWitness
+
 describe('fromRpc', () => {
   test('default', () => {
     const request = TransactionRequest.fromRpc({
@@ -69,6 +137,21 @@ describe('fromRpc', () => {
     expect(request.nonceKey).toBe(255n)
   })
 
+  test('behavior: multisig witness', () => {
+    const request = TransactionRequest.fromRpc({
+      from: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+      multisigWitness: multisigWitnessRpc,
+      type: '0x76',
+    })
+
+    expect(request.multisigWitness?.config.version).toBe(0n)
+    const nested = request.multisigWitness?.approvals[1]
+    expect(nested?.type).toBe('multisig')
+    if (nested?.type !== 'multisig') throw new Error('expected multisig')
+    expect(nested.witness.config.version).toBe(1n)
+    expect(nested.witness.approvals[0]?.keyType).toBe('webAuthn')
+  })
+
   test('behavior: empty', () => {
     const request = TransactionRequest.fromRpc({})
     expect(request).toMatchInlineSnapshot('{}')
@@ -122,6 +205,20 @@ describe('toRpc', () => {
       }
     `)
   })
+
+  test('behavior: multisig witness', () => {
+    const request = TransactionRequest.toRpc({
+      from: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+      multisigWitness,
+    })
+
+    expect(request.multisigWitness?.config.version).toBe(0)
+    const nested = request.multisigWitness?.approvals[1]
+    expect(nested?.type).toBe('multisig')
+    if (nested?.type !== 'multisig') throw new Error('expected multisig')
+    expect(nested.witness.config.version).toBe(1)
+    expect(request.type).toBe('0x76')
+  })
 })
 
 describe('roundtrip', () => {
@@ -144,6 +241,7 @@ describe('roundtrip', () => {
       nonceKey: 255n,
       gas: 100000n,
       maxFeePerGas: 1000000000n,
+      multisigWitness,
     }
 
     const rpc = TransactionRequest.toRpc(original)
@@ -164,6 +262,7 @@ describe('roundtrip', () => {
     expect(converted.nonceKey).toBe(original.nonceKey)
     expect(converted.gas).toBe(original.gas)
     expect(converted.maxFeePerGas).toBe(original.maxFeePerGas)
+    expect(converted.multisigWitness).toEqual(original.multisigWitness)
     expect(converted.type).toBe('tempo')
   })
 
@@ -181,6 +280,7 @@ describe('roundtrip', () => {
       validAfter: '0x32',
       nonceKey: '0xff',
       gas: '0x186a0',
+      multisigWitness: multisigWitnessRpc,
       type: '0x76',
     }
 
@@ -193,6 +293,7 @@ describe('roundtrip', () => {
     expect(rpc.validAfter).toBe(original.validAfter)
     expect(rpc.nonceKey).toBe(original.nonceKey)
     expect(rpc.gas).toBe(original.gas)
+    expect(rpc.multisigWitness).toEqual(original.multisigWitness)
     expect(rpc.type).toBe('0x76')
   })
 })

package/tempo/TransactionRequest.ts

@@ -4,6 +4,7 @@ import type { Compute } from '../core/internal/types.js'
 import * as ox_TransactionRequest from '../core/TransactionRequest.js'
 import * as AuthorizationTempo from './AuthorizationTempo.js'
 import * as KeyAuthorization from './KeyAuthorization.js'
+import * as MultisigWitness from './MultisigWitness.js'
 import * as TempoAddress from './TempoAddress.js'
 import * as TokenId from './TokenId.js'
 import * as Transaction from './Transaction.js'
@@ -38,6 +39,7 @@ export type TransactionRequest<
     keyType?: KeyType | undefined
     feePayer?: boolean | undefined
     feeToken?: TokenId.TokenIdOrAddress<addressType> | undefined
+    multisigWitness?: MultisigWitness.MultisigWitness<bigintType> | undefined
     nonceKey?: 'random' | bigintType | undefined
     validBefore?: numberType | undefined
     validAfter?: numberType | undefined
@@ -47,11 +49,12 @@ export type TransactionRequest<
 /** RPC representation of a {@link ox#TransactionRequest.TransactionRequest}. */
 export type Rpc = Omit<
   TransactionRequest<Hex.Hex, Hex.Hex, string, Hex.Hex>,
-  'authorizationList' | 'feeToken' | 'keyAuthorization'
+  'authorizationList' | 'feeToken' | 'keyAuthorization' | 'multisigWitness'
 > & {
   authorizationList?: AuthorizationTempo.ListRpc | undefined
   feeToken?: Hex.Hex | undefined
   keyAuthorization?: KeyAuthorization.Rpc | undefined
+  multisigWitness?: MultisigWitness.Rpc | undefined
   nonceKey?: Hex.Hex | undefined
 }
 
@@ -76,7 +79,7 @@ export type Rpc = Omit<
  * @returns A transaction request.
  */
 export function fromRpc(request: Rpc): TransactionRequest {
-  const { authorizationList: _, ...rest } = request
+  const { authorizationList: _, multisigWitness: __, ...rest } = request
   const request_ = ox_TransactionRequest.fromRpc(
     rest as any,
   ) as TransactionRequest
@@ -107,6 +110,8 @@ export function fromRpc(request: Rpc): TransactionRequest {
     request_.keyAuthorization = KeyAuthorization.fromRpc(
       request.keyAuthorization,
     )
+  if (request.multisigWitness)
+    request_.multisigWitness = MultisigWitness.fromRpc(request.multisigWitness)
   if (typeof request.validBefore !== 'undefined')
     request_.validBefore = Hex.toNumber(request.validBefore as Hex.Hex)
   if (typeof request.validAfter !== 'undefined')
@@ -120,6 +125,7 @@ export function fromRpc(request: Rpc): TransactionRequest {
 export declare namespace fromRpc {
   export type ErrorType =
     | AuthorizationTempo.fromRpcList.ErrorType
+    | MultisigWitness.fromRpc.ErrorType
     | Hex.toNumber.ErrorType
     | Hex.toBigInt.ErrorType
     | Errors.GlobalErrorType
@@ -204,6 +210,8 @@ export function toRpc(request: TransactionRequest): Rpc {
     request_rpc.keyAuthorization = KeyAuthorization.toRpc(
       request.keyAuthorization,
     )
+  if (request.multisigWitness)
+    request_rpc.multisigWitness = MultisigWitness.toRpc(request.multisigWitness)
   if (typeof request.validBefore !== 'undefined')
     request_rpc.validBefore = Hex.fromNumber(request.validBefore)
   if (typeof request.validAfter !== 'undefined')
@@ -222,6 +230,7 @@ export function toRpc(request: TransactionRequest): Rpc {
     typeof request.feePayer !== 'undefined' ||
     typeof request.feeToken !== 'undefined' ||
     typeof request.keyAuthorization !== 'undefined' ||
+    typeof request.multisigWitness !== 'undefined' ||
     typeof request.nonceKey !== 'undefined' ||
     typeof request.validBefore !== 'undefined' ||
     typeof request.validAfter !== 'undefined' ||
@@ -240,6 +249,7 @@ export function toRpc(request: TransactionRequest): Rpc {
 export declare namespace toRpc {
   export type ErrorType =
     | AuthorizationTempo.toRpcList.ErrorType
+    | MultisigWitness.toRpc.ErrorType
     | Hex.fromNumber.ErrorType
     | Errors.GlobalErrorType
 }

package/tempo/index.ts

@@ -159,6 +159,15 @@ export * as MultisigConfig from './MultisigConfig.js'
  * @category Reference
  */
 export * as MultisigOperation from './MultisigOperation.js'
+/**
+ * Native multisig RPC simulation witness utilities.
+ *
+ * Converts complete root and nested owner witnesses between their domain and
+ * Tempo JSON-RPC representations.
+ *
+ * @category Reference
+ */
+export * as MultisigWitness from './MultisigWitness.js'
 /**
  * Utilities for constructing period durations (in seconds) for recurring spending limits.
  *

package/version.ts

@@ -1,2 +1,2 @@
 /** @internal */
-export const version = '0.14.39'
+export const version = '0.14.41'