ox 0.14.38 → 0.14.40

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

@@ -1,4 +1,5 @@
 import { expectTypeOf, test } from 'vitest'
+import * as MultisigConfig from './MultisigConfig.js'
 import * as SignatureEnvelope from './SignatureEnvelope.js'
 
 const signatureRpc = {
@@ -17,67 +18,81 @@ const signature = {
   type: 'secp256k1',
 } as const satisfies SignatureEnvelope.Secp256k1
 
+const config = MultisigConfig.from({
+  owners: [
+    {
+      owner: '0x1111111111111111111111111111111111111111',
+      weight: 1,
+    },
+  ],
+  threshold: 1,
+})
+
 test('toRpc preserves the signature type', () => {
   expectTypeOf(
     SignatureEnvelope.toRpc(signature),
   ).toEqualTypeOf<SignatureEnvelope.Secp256k1Rpc>()
 })
 
-test('MultisigRpc uses static initialized and bootstrap shapes', () => {
-  const initialized = {
+test('MultisigRpc carries one complete witness shape', () => {
+  const rpc = {
     account: '0x1111111111111111111111111111111111111111',
+    config: MultisigConfig.toRpc(config),
     signatures: [signatureRpc],
   } as const satisfies SignatureEnvelope.MultisigRpc
-  const bootstrap = {
-    init: {
-      owners: [
-        {
-          owner: '0x1111111111111111111111111111111111111111',
-          weight: 1,
-        },
-      ],
-      threshold: 1,
-    },
-    signatures: [signatureRpc],
-  } as const satisfies SignatureEnvelope.MultisigRpc
-  const bootstrapWithAccountUndefined: SignatureEnvelope.MultisigRpc = {
-    ...bootstrap,
-    account: undefined,
-  }
 
-  expectTypeOf(initialized.signatures).toMatchTypeOf<
-    readonly SignatureEnvelope.SignatureEnvelopeRpc[]
-  >()
-  expectTypeOf(bootstrap.signatures).toMatchTypeOf<
+  expectTypeOf(rpc.config).toMatchTypeOf<MultisigConfig.Rpc>()
+  expectTypeOf(rpc.signatures).toMatchTypeOf<
     readonly SignatureEnvelope.SignatureEnvelopeRpc[]
   >()
-  expectTypeOf(
-    bootstrapWithAccountUndefined,
-  ).toMatchTypeOf<SignatureEnvelope.MultisigRpc>()
   expectTypeOf<
-    SignatureEnvelope.GetType<typeof bootstrap>
+    SignatureEnvelope.GetType<typeof rpc>
   >().toEqualTypeOf<'multisig'>()
 })
 
-test('MultisigRpc rejects legacy shapes', () => {
-  const combined = {
+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',
-    init: {
-      owners: [
-        {
-          owner: '0x1111111111111111111111111111111111111111',
-          weight: 1,
-        },
-      ],
-      threshold: 1,
-    },
     signatures: [signatureRpc],
   } as const
-  // @ts-expect-error Bootstrap RPC signatures omit `account`.
-  const combinedRpc: SignatureEnvelope.MultisigRpc = combined
+  // @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.
@@ -85,13 +100,15 @@ test('MultisigRpc rejects legacy shapes', () => {
 
   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(combinedRpc).toEqualTypeOf<SignatureEnvelope.MultisigRpc>()
+  expectTypeOf(accountOnlyRpc).toEqualTypeOf<SignatureEnvelope.MultisigRpc>()
+  expectTypeOf(initRpc).toEqualTypeOf<SignatureEnvelope.MultisigRpc>()
   expectTypeOf(serializedRpc).toEqualTypeOf<SignatureEnvelope.MultisigRpc>()
   expectTypeOf(taggedRpc).toEqualTypeOf<SignatureEnvelope.MultisigRpc>()
 })