ox 0.14.27 → 0.14.28

package/tempo/MultisigConfig.ts

@@ -0,0 +1,423 @@
+import * as Address from '../core/Address.js'
+import type * as Bytes from '../core/Bytes.js'
+import * as Errors from '../core/Errors.js'
+import * as Hash from '../core/Hash.js'
+import * as Hex from '../core/Hex.js'
+import type { Compute } from '../core/internal/types.js'
+
+/** Maximum number of owners allowed in a native multisig config. */
+export const maxOwners = 10
+
+/** Maximum encoded byte length for one primitive owner approval. */
+export const maxOwnerSignatureBytes = 2049
+
+/** Tempo signature type byte for native multisig signatures. */
+export const signatureTypeByte = '0x05' as const
+
+/** Zero 32-byte salt (the default when no salt is provided). */
+export const zeroSalt = `0x${'00'.repeat(32)}` as const
+
+/** Domain prefix for the native multisig account address derivation. */
+const accountDomain = 'tempo:multisig:account'
+
+/** Domain prefix for the native multisig config ID derivation. */
+const configDomain = 'tempo:multisig:config'
+
+/** Domain prefix for native multisig owner approvals. */
+const signatureDomain = 'tempo:multisig:signature'
+
+/**
+ * Native multisig configuration. Determines the permanent config ID and the
+ * stable multisig account address.
+ */
+export type Config<numberType = number> = Compute<{
+  /**
+   * Caller-chosen 32-byte salt mixed into the permanent config ID. Defaults to
+   * the zero salt (`MultisigConfig.zeroSalt`) when omitted.
+   */
+  salt?: Hex.Hex | undefined
+  /** Minimum total owner weight required to authorize a transaction. */
+  threshold: numberType
+  /** Weighted owner list (strictly ascending by `owner` address). */
+  owners: readonly Owner<numberType>[]
+}>
+
+/** Native multisig owner entry. */
+export type Owner<numberType = number> = {
+  /** Owner address (recovered from the owner's primitive signature). */
+  owner: Address.Address
+  /** Nonzero owner weight. */
+  weight: numberType
+}
+
+/** RLP tuple representation of a {@link ox#MultisigConfig.Config}. */
+export type Tuple = readonly [
+  salt: Hex.Hex,
+  threshold: Hex.Hex,
+  owners: readonly Hex.Hex[][],
+]
+
+/**
+ * Asserts that a native multisig {@link ox#MultisigConfig.Config} is valid.
+ *
+ * Mirrors the Tempo `validate_multisig_config` rules: owners non-empty and
+ * `<= maxOwners`, strictly ascending unique nonzero owner addresses, nonzero
+ * owner weights, `threshold >= 1`, total weight `<= u32::MAX`, and
+ * `threshold <= total weight`.
+ *
+ * @example
+ * ```ts twoslash
+ * import { MultisigConfig } from 'ox/tempo'
+ *
+ * MultisigConfig.assert({
+ *   threshold: 1,
+ *   owners: [
+ *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
+ *   ],
+ * })
+ * ```
+ *
+ * @param config - The multisig config.
+ */
+export function assert<numberType = number>(config: Config<numberType>): void {
+  const { salt, threshold, owners } = config
+
+  if (typeof salt !== 'undefined' && Hex.size(salt) !== 32)
+    throw new InvalidConfigError({ reason: 'salt must be 32 bytes' })
+  if (owners.length === 0)
+    throw new InvalidConfigError({ reason: 'owners cannot be empty' })
+  if (owners.length > maxOwners)
+    throw new InvalidConfigError({ reason: 'too many owners' })
+  if (Number(threshold) < 1)
+    throw new InvalidConfigError({ reason: 'threshold cannot be zero' })
+
+  let totalWeight = 0
+  let previous: bigint | undefined
+  for (const owner of owners) {
+    if (!Address.validate(owner.owner) || Hex.toBigInt(owner.owner) === 0n)
+      throw new InvalidConfigError({ reason: 'owner cannot be zero' })
+    if (Number(owner.weight) < 1)
+      throw new InvalidConfigError({ reason: 'owner weight cannot be zero' })
+
+    const current = Hex.toBigInt(owner.owner)
+    if (typeof previous !== 'undefined' && previous >= current)
+      throw new InvalidConfigError({
+        reason: 'owners must be strictly ascending',
+      })
+    previous = current
+
+    totalWeight += Number(owner.weight)
+  }
+
+  if (totalWeight > 0xffffffff)
+    throw new InvalidConfigError({
+      reason: 'total owner weight exceeds u32 max',
+    })
+  if (Number(threshold) > totalWeight)
+    throw new InvalidConfigError({
+      reason: 'threshold exceeds total owner weight',
+    })
+}
+
+export declare namespace assert {
+  type ErrorType = InvalidConfigError | Errors.GlobalErrorType
+}
+
+/**
+ * Normalizes a native multisig {@link ox#MultisigConfig.Config}.
+ *
+ * Sorts owners into strictly ascending `owner` address order (the canonical
+ * form required for config ID derivation) and asserts the config is valid.
+ *
+ * @example
+ * ```ts twoslash
+ * import { MultisigConfig } from 'ox/tempo'
+ *
+ * const config = MultisigConfig.from({
+ *   threshold: 2,
+ *   owners: [
+ *     { owner: '0x2222222222222222222222222222222222222222', weight: 1 },
+ *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
+ *   ],
+ * })
+ * // owners are now sorted ascending by address
+ * ```
+ *
+ * @param config - The multisig config.
+ * @returns The normalized multisig config.
+ */
+export function from<numberType = number>(
+  config: Config<numberType>,
+): Config<numberType> {
+  const owners = [...config.owners].sort((a, b) =>
+    Hex.toBigInt(a.owner) < Hex.toBigInt(b.owner) ? -1 : 1,
+  )
+  const normalized = {
+    salt: config.salt ? Hex.padLeft(config.salt, 32) : zeroSalt,
+    threshold: config.threshold,
+    owners,
+  } as Config<numberType>
+  assert(normalized)
+  return normalized
+}
+
+/**
+ * Converts an RLP {@link ox#MultisigConfig.Tuple} back to a
+ * {@link ox#MultisigConfig.Config}.
+ *
+ * @example
+ * ```ts twoslash
+ * import { MultisigConfig } from 'ox/tempo'
+ *
+ * const config = MultisigConfig.fromTuple([
+ *   `0x${'00'.repeat(32)}`,
+ *   '0x01',
+ *   [['0x1111111111111111111111111111111111111111', '0x01']],
+ * ])
+ * ```
+ *
+ * @param tuple - The RLP tuple.
+ * @returns The multisig config.
+ */
+export function fromTuple(tuple: Tuple): Config {
+  const [salt, threshold, owners] = tuple
+  return {
+    salt: salt && salt !== '0x' ? Hex.padLeft(salt, 32) : zeroSalt,
+    threshold: threshold === '0x' ? 0 : Hex.toNumber(threshold),
+    owners: owners.map((owner) => {
+      const [ownerAddress, weight] = owner as readonly Hex.Hex[]
+      return {
+        owner: ownerAddress as Address.Address,
+        weight: !weight || weight === '0x' ? 0 : Hex.toNumber(weight),
+      }
+    }),
+  }
+}
+
+/**
+ * Derives the stable native multisig account address.
+ *
+ * `keccak256("tempo:multisig:account" || config_id)[12:32]`.
+ *
+ * @example
+ * ```ts twoslash
+ * import { MultisigConfig } from 'ox/tempo'
+ *
+ * const config = MultisigConfig.from({
+ *   threshold: 1,
+ *   owners: [
+ *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
+ *   ],
+ * })
+ *
+ * const address = MultisigConfig.getAddress({ config })
+ * ```
+ *
+ * @param value - The config or config ID to derive the address from.
+ * @returns The multisig account address.
+ */
+export function getAddress(value: getAddress.Value): Address.Address {
+  const id = 'configId' in value ? value.configId : toId(value.config)
+  const hash = Hash.keccak256(Hex.concat(Hex.fromString(accountDomain), id))
+  return Address.from(Hex.slice(hash, 12, 32))
+}
+
+export declare namespace getAddress {
+  type Value = { config: Config } | { configId: Hex.Hex }
+
+  type ErrorType =
+    | toId.ErrorType
+    | Address.from.ErrorType
+    | Hash.keccak256.ErrorType
+    | Hex.concat.ErrorType
+    | Hex.slice.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Computes the digest a native multisig owner approves (signs).
+ *
+ * `keccak256("tempo:multisig:signature" || inner_digest || account || config_id)`,
+ * where `inner_digest` is the transaction sign payload
+ * ({@link ox#TxEnvelopeTempo.(getSignPayload:function)}).
+ *
+ * @example
+ * ```ts twoslash
+ * import { MultisigConfig, TxEnvelopeTempo } from 'ox/tempo'
+ *
+ * const config = MultisigConfig.from({
+ *   threshold: 1,
+ *   owners: [
+ *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
+ *   ],
+ * })
+ * const configId = MultisigConfig.toId(config)
+ * const account = MultisigConfig.getAddress({ configId })
+ *
+ * const envelope = TxEnvelopeTempo.from({
+ *   chainId: 1,
+ *   calls: [],
+ * })
+ *
+ * const digest = MultisigConfig.getSignPayload({
+ *   payload: TxEnvelopeTempo.getSignPayload(envelope),
+ *   account,
+ *   configId,
+ * })
+ * ```
+ *
+ * @param value - The digest derivation parameters.
+ * @returns The owner approval digest.
+ */
+export function getSignPayload(value: getSignPayload.Value): Hex.Hex {
+  const { payload, account, configId } = value
+  return Hash.keccak256(
+    Hex.concat(
+      Hex.fromString(signatureDomain),
+      Hex.from(payload),
+      account,
+      configId,
+    ),
+  )
+}
+
+export declare namespace getSignPayload {
+  type Value = {
+    /** The inner transaction sign payload (`tx.signature_hash()`). */
+    payload: Hex.Hex | Bytes.Bytes
+    /** The native multisig account address. */
+    account: Address.Address
+    /** The permanent config ID. */
+    configId: Hex.Hex
+  }
+
+  type ErrorType =
+    | Hash.keccak256.ErrorType
+    | Hex.concat.ErrorType
+    | Hex.from.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Derives the permanent config ID for a native multisig
+ * {@link ox#MultisigConfig.Config}.
+ *
+ * Preimage (fixed-width big-endian, **not** RLP):
+ * `keccak256("tempo:multisig:config" || salt || be_u32(threshold) || be_u32(owners.length) || (owner || be_u32(weight)) for each owner)`.
+ *
+ * @example
+ * ```ts twoslash
+ * import { MultisigConfig } from 'ox/tempo'
+ *
+ * const config = MultisigConfig.from({
+ *   threshold: 1,
+ *   owners: [
+ *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
+ *   ],
+ * })
+ *
+ * const configId = MultisigConfig.toId(config)
+ * ```
+ *
+ * @param config - The multisig config.
+ * @returns The 32-byte config ID.
+ */
+export function toId(config: Config): Hex.Hex {
+  assert(config)
+  const id = Hash.keccak256(
+    Hex.concat(
+      Hex.fromString(configDomain),
+      Hex.padLeft(config.salt ?? zeroSalt, 32),
+      Hex.fromNumber(config.threshold, { size: 4 }),
+      Hex.fromNumber(config.owners.length, { size: 4 }),
+      ...config.owners.flatMap((owner) => [
+        owner.owner,
+        Hex.fromNumber(owner.weight, { size: 4 }),
+      ]),
+    ),
+  )
+  if (Hex.toBigInt(id) === 0n)
+    throw new InvalidConfigError({ reason: 'config ID cannot be zero' })
+  return id
+}
+
+export declare namespace toId {
+  type ErrorType =
+    | assert.ErrorType
+    | Hash.keccak256.ErrorType
+    | Hex.concat.ErrorType
+    | Hex.fromNumber.ErrorType
+    | Hex.fromString.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Converts a {@link ox#MultisigConfig.Config} to its RLP tuple form (carried
+ * by the multisig signature `init`).
+ *
+ * Tuple shape: `[salt, threshold, [[owner, weight], ...]]`. The
+ * 32-byte `salt` encodes as a full fixed-width string; other integers use
+ * canonical RLP encoding (zero values encode as `0x`).
+ *
+ * @example
+ * ```ts twoslash
+ * import { MultisigConfig } from 'ox/tempo'
+ *
+ * const tuple = MultisigConfig.toTuple({
+ *   threshold: 1,
+ *   owners: [
+ *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
+ *   ],
+ * })
+ * ```
+ *
+ * @param config - The multisig config.
+ * @returns The RLP tuple.
+ */
+export function toTuple(config: Config): Tuple {
+  assert(config)
+  const owners = config.owners.map(
+    (owner) => [owner.owner, Hex.fromNumber(owner.weight)] as Hex.Hex[],
+  )
+  // `salt` is a fixed 32-byte value: it RLP-encodes as a full 32-byte string
+  // (including the zero salt), never trimmed like an integer.
+  const salt = config.salt ? Hex.padLeft(config.salt, 32) : zeroSalt
+  return [salt, Hex.fromNumber(config.threshold), owners] as const
+}
+
+/**
+ * Validates a native multisig {@link ox#MultisigConfig.Config}. Returns `true`
+ * if valid, `false` otherwise.
+ *
+ * @example
+ * ```ts twoslash
+ * import { MultisigConfig } from 'ox/tempo'
+ *
+ * const valid = MultisigConfig.validate({
+ *   threshold: 1,
+ *   owners: [
+ *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
+ *   ],
+ * })
+ * // @log: true
+ * ```
+ *
+ * @param config - The multisig config.
+ * @returns Whether the config is valid.
+ */
+export function validate(config: Config): boolean {
+  try {
+    assert(config)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Thrown when a native multisig config is invalid. */
+export class InvalidConfigError extends Errors.BaseError {
+  override readonly name = 'MultisigConfig.InvalidConfigError'
+  constructor({ reason }: { reason: string }) {
+    super(`Invalid native multisig config: ${reason}.`)
+  }
+}

package/tempo/SignatureEnvelope.test.ts

@@ -9,6 +9,7 @@ import {
   WebCryptoP256,
 } from 'ox'
 import { describe, expect, test } from 'vitest'
+import * as MultisigConfig from './MultisigConfig.js'
 import * as SignatureEnvelope from './SignatureEnvelope.js'
 
 const publicKey = PublicKey.from({
@@ -512,7 +513,7 @@ describe('deserialize', () => {
         SignatureEnvelope.deserialize('0xdeadbeef'),
       ).toThrowErrorMatchingInlineSnapshot(
         `
-        [SignatureEnvelope.InvalidSerializedError: Unable to deserialize signature envelope: Unknown signature type identifier: 0xde. Expected 0x01 (P256), 0x02 (WebAuthn), 0x03 (Keychain V1), or 0x04 (Keychain V2)
+        [SignatureEnvelope.InvalidSerializedError: Unable to deserialize signature envelope: Unknown signature type identifier: 0xde. Expected 0x01 (P256), 0x02 (WebAuthn), 0x03 (Keychain V1), 0x04 (Keychain V2), or 0x05 (Multisig)
 
         Serialized: 0xdeadbeef]
       `,
@@ -672,7 +673,7 @@ describe('deserialize', () => {
         SignatureEnvelope.deserialize(unknownType),
       ).toThrowErrorMatchingInlineSnapshot(
         `
-        [SignatureEnvelope.InvalidSerializedError: Unable to deserialize signature envelope: Unknown signature type identifier: 0xff. Expected 0x01 (P256), 0x02 (WebAuthn), 0x03 (Keychain V1), or 0x04 (Keychain V2)
+        [SignatureEnvelope.InvalidSerializedError: Unable to deserialize signature envelope: Unknown signature type identifier: 0xff. Expected 0x01 (P256), 0x02 (WebAuthn), 0x03 (Keychain V1), 0x04 (Keychain V2), or 0x05 (Multisig)
 
         Serialized: 0xff000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000]
       `,
@@ -1696,6 +1697,67 @@ describe('serialize', () => {
   })
 })
 
+describe('sortMultisigApprovals', () => {
+  const account = '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' as const
+  const configId = `0x${'11'.repeat(32)}` as const
+  const payload = `0x${'42'.repeat(32)}` as const
+  const digest = MultisigConfig.getSignPayload({
+    account,
+    configId,
+    payload,
+  })
+
+  const owners = Array.from({ length: 3 }, () => {
+    const privateKey = Secp256k1.randomPrivateKey()
+    const address = Address.fromPublicKey(
+      Secp256k1.getPublicKey({ privateKey }),
+    )
+    const signature = SignatureEnvelope.from(
+      Secp256k1.sign({ payload: digest, privateKey }),
+    )
+    return { address, signature } as const
+  })
+  const ascending = [...owners].sort((a, b) =>
+    Hex.toBigInt(a.address) < Hex.toBigInt(b.address) ? -1 : 1,
+  )
+
+  test('behavior: orders approvals ascending by recovered owner address', () => {
+    const ordered = SignatureEnvelope.sortMultisigApprovals({
+      account,
+      configId,
+      payload,
+      // Provide approvals in reverse of the canonical order.
+      signatures: [...ascending].reverse().map((owner) => owner.signature),
+    })
+    expect(ordered).toEqual(ascending.map((owner) => owner.signature))
+  })
+
+  test('behavior: already-sorted input is unchanged', () => {
+    const signatures = ascending.map((owner) => owner.signature)
+    expect(
+      SignatureEnvelope.sortMultisigApprovals({
+        account,
+        configId,
+        payload,
+        signatures,
+      }),
+    ).toEqual(signatures)
+  })
+
+  test('behavior: recovered order matches the config owner order', () => {
+    const ordered = SignatureEnvelope.sortMultisigApprovals({
+      account,
+      configId,
+      payload,
+      signatures: owners.map((owner) => owner.signature),
+    })
+    const recovered = ordered.map((signature) =>
+      SignatureEnvelope.extractAddress({ payload: digest, signature }),
+    )
+    expect(recovered).toEqual(ascending.map((owner) => owner.address))
+  })
+})
+
 describe('validate', () => {
   describe('secp256k1', () => {
     test('behavior: returns true for valid signature', () => {
@@ -2692,3 +2754,152 @@ describe('CoercionError', () => {
     )
   })
 })
+
+describe('multisig', () => {
+  const account = '0x8ba6d26ff5c4e82ba0c8caf8c8ca794e1489a7ae'
+  const configId =
+    '0x01781fe551182476f2422c759e82d81c92e3263737afbbad57def6e8b69d21f5'
+
+  // P256 signatures do not carry `yParity` in the wire format, so use a clean
+  // inner signature for round-trip equality checks.
+  const innerP256 = SignatureEnvelope.from({
+    signature: { r: p256Signature.r, s: p256Signature.s },
+    publicKey,
+    prehash: true,
+  })
+
+  const envelope = SignatureEnvelope.from({
+    type: 'multisig',
+    account,
+    configId,
+    signatures: [SignatureEnvelope.from(signature_secp256k1), innerP256],
+  })
+
+  test('serialize: type byte 0x05 prefix', () => {
+    const serialized = SignatureEnvelope.serialize(envelope)
+    expect(serialized.startsWith('0x05')).toBe(true)
+  })
+
+  test('serialize/deserialize round-trip', () => {
+    const serialized = SignatureEnvelope.serialize(envelope)
+    expect(SignatureEnvelope.deserialize(serialized)).toEqual(envelope)
+  })
+
+  test('getType', () => {
+    expect(SignatureEnvelope.getType(envelope)).toBe('multisig')
+  })
+
+  test('extractAddress returns the multisig account', () => {
+    expect(
+      SignatureEnvelope.extractAddress({
+        payload: '0xdeadbeef',
+        signature: envelope,
+      }),
+    ).toBe(account)
+  })
+
+  test('toRpc/fromRpc round-trip', () => {
+    const rpc = SignatureEnvelope.toRpc(envelope)
+    expect(rpc.type).toBe('multisig')
+    expect(SignatureEnvelope.fromRpc(rpc)).toEqual(envelope)
+  })
+
+  test('assert: missing properties', () => {
+    expect(() =>
+      SignatureEnvelope.assert({ type: 'multisig', account } as never),
+    ).toThrowError()
+  })
+
+  describe('init (bootstrap)', () => {
+    const init = {
+      salt: `0x${'00'.repeat(32)}` as const,
+      threshold: 1,
+      owners: [
+        {
+          owner: '0x1111111111111111111111111111111111111111' as const,
+          weight: 1,
+        },
+      ],
+    }
+
+    const bootstrapEnvelope = SignatureEnvelope.from({
+      type: 'multisig',
+      account,
+      configId,
+      signatures: [SignatureEnvelope.from(signature_secp256k1), innerP256],
+      init,
+    })
+
+    test('serialize/deserialize round-trip with init', () => {
+      const serialized = SignatureEnvelope.serialize(bootstrapEnvelope)
+      expect(SignatureEnvelope.deserialize(serialized)).toEqual(
+        bootstrapEnvelope,
+      )
+    })
+
+    test('serialize/deserialize round-trip preserves non-zero salt', () => {
+      const salted = SignatureEnvelope.from({
+        type: 'multisig',
+        account,
+        configId,
+        signatures: [SignatureEnvelope.from(signature_secp256k1), innerP256],
+        init: { ...init, salt: `0x${'42'.repeat(32)}` },
+      })
+      const serialized = SignatureEnvelope.serialize(salted)
+      const deserialized = SignatureEnvelope.deserialize(
+        serialized,
+      ) as SignatureEnvelope.Multisig
+      expect(deserialized.init?.salt).toBe(`0x${'42'.repeat(32)}`)
+      expect(deserialized).toEqual(salted)
+    })
+
+    test('absent init has no `init` key after deserialize', () => {
+      const serialized = SignatureEnvelope.serialize(envelope)
+      const deserialized = SignatureEnvelope.deserialize(serialized)
+      expect('init' in deserialized).toBe(false)
+    })
+
+    test('init absent vs present produce different serializations', () => {
+      expect(SignatureEnvelope.serialize(envelope)).not.toBe(
+        SignatureEnvelope.serialize(bootstrapEnvelope),
+      )
+    })
+
+    test('toRpc/fromRpc round-trip with init', () => {
+      const rpc = SignatureEnvelope.toRpc(bootstrapEnvelope)
+      expect(rpc.init).toEqual(init)
+      expect(SignatureEnvelope.fromRpc(rpc)).toEqual(bootstrapEnvelope)
+    })
+
+    test('toRpc encodes owner approvals as serialized hex (node `Vec<Bytes>`)', () => {
+      const multisig = bootstrapEnvelope as SignatureEnvelope.Multisig
+      const rpc = SignatureEnvelope.toRpc(
+        multisig,
+      ) as SignatureEnvelope.MultisigRpc
+      expect(rpc.signatures).toEqual(
+        multisig.signatures.map((s) => SignatureEnvelope.serialize(s)),
+      )
+    })
+
+    test('fromRpc detects multisig by shape (no `type` field)', () => {
+      const rpc = SignatureEnvelope.toRpc(bootstrapEnvelope)
+      // The node omits the `type` discriminant; detection is shape-based.
+      const { type: _type, ...untyped } = rpc
+      expect(SignatureEnvelope.fromRpc(untyped as never)).toEqual(
+        bootstrapEnvelope,
+      )
+    })
+
+    test('assert: invalid init config throws', () => {
+      expect(() =>
+        SignatureEnvelope.assert({
+          type: 'multisig',
+          account,
+          configId,
+          signatures: [],
+          init: { threshold: 1, owners: [] },
+        } as never),
+      ).toThrowError()
+    })
+  })
+})