ox 0.14.37 → 0.14.39

package/tempo/MultisigOperation.ts

@@ -14,7 +14,7 @@ export type Base<quantity = bigint> = {
   /** Every retained serialized owner approval. */
   approvals: readonly Hex.Hex[]
   /** Root configuration used to verify approvals. */
-  config: MultisigConfig.Config
+  config: MultisigConfig.Config<quantity>
   /** Root configuration version. */
   configVersion: quantity
   /** Unix creation time in milliseconds. */
@@ -76,6 +76,250 @@ export type Rpc = Operation<Hex.Hex>
 /** Maximum supported multisig configuration version. */
 const maxConfigVersion = 2n ** 64n - 1n
 
+/**
+ * Derives the deterministic hash for a multisig operation.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { MultisigOperation } from 'ox/tempo'
+ *
+ * const hash = MultisigOperation.getHash({
+ *   account,
+ *   configVersion: 1n,
+ *   transaction,
+ *   type: 'transaction',
+ * })
+ * ```
+ *
+ * @param options - Operation payload and multisig identity.
+ * @returns The operation hash signed by each owner.
+ */
+export function getHash(options: getHash.Options): Hex.Hex {
+  const { account, configVersion } = options
+  const payload =
+    options.type === 'transaction'
+      ? TxEnvelopeTempo.getSignPayload(
+          TxEnvelopeTempo.deserialize(
+            options.transaction as TxEnvelopeTempo.Serialized,
+          ),
+        )
+      : KeyAuthorization_.getSignPayload(
+          KeyAuthorization_.deserialize(options.keyAuthorization),
+        )
+  return MultisigConfig.getSignPayload({
+    account,
+    config: { version: configVersion },
+    payload,
+  })
+}
+
+export declare namespace getHash {
+  /** Parameters for `getHash`. */
+  export type Options = {
+    /** Root multisig account. */
+    account: Address.Address
+    /** Root configuration version. */
+    configVersion: bigint
+  } & (
+    | {
+        /** Canonical serialized key authorization. */
+        keyAuthorization: Hex.Hex
+        /** Operation kind. */
+        type: 'keyAuthorization'
+      }
+    | {
+        /** Canonical serialized Tempo envelope without its outer sender signature. */
+        transaction: Hex.Hex
+        /** Operation kind. */
+        type: 'transaction'
+      }
+  )
+
+  /** Error type for `getHash`. */
+  export type ErrorType =
+    | KeyAuthorization_.deserialize.ErrorType
+    | KeyAuthorization_.getSignPayload.ErrorType
+    | MultisigConfig.getSignPayload.ErrorType
+    | TxEnvelopeTempo.deserialize.ErrorType
+    | TxEnvelopeTempo.getSignPayload.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Validates, deduplicates, and selects owner approvals for an operation.
+ *
+ * The function retains one canonical approval per owner. It selects the
+ * smallest deterministic quorum by owner weight, then orders the selected
+ * approvals by owner address for serialization.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { MultisigOperation } from 'ox/tempo'
+ *
+ * const selection = await MultisigOperation.selectApprovals({
+ *   account,
+ *   approvals,
+ *   config,
+ *   hash,
+ *   resolveConfig,
+ * })
+ * ```
+ *
+ * @param options - Approval selection parameters.
+ * @returns The retained approvals and deterministic quorum selection.
+ */
+export async function selectApprovals(
+  options: selectApprovals.Options,
+): Promise<selectApprovals.ReturnValue> {
+  const { account, approvals, hash, resolveConfig } = options
+  if (!Address.validate(account) || Hex.toBigInt(account) === 0n)
+    throw new InvalidApprovalError({ reason: 'account is invalid' })
+  if (!Hash.validate(hash))
+    throw new InvalidApprovalError({ reason: 'hash is invalid' })
+  return selectApprovals_internal(
+    {
+      account,
+      approvals,
+      config: MultisigConfig.from(options.config),
+      hash,
+      resolveConfig,
+    },
+    [account.toLowerCase()],
+  )
+}
+
+export declare namespace selectApprovals {
+  /** Parameters for `selectApprovals`. */
+  export type Options = {
+    /** Root multisig account. */
+    account: Address.Address
+    /** Serialized primitive or nested owner approvals. */
+    approvals: readonly SignatureEnvelope.Serialized[]
+    /** Current root multisig configuration. */
+    config: MultisigConfig.Config
+    /** Deterministic operation hash approved by root owners. */
+    hash: Hex.Hex
+    /** Resolves the current configuration of a nested multisig owner. */
+    resolveConfig?: ResolveConfig | undefined
+  }
+
+  /** Resolves an initialized nested multisig configuration. */
+  export type ResolveConfig = (
+    options: ResolveConfigOptions,
+  ) => ResolvedConfig | Promise<ResolvedConfig>
+
+  /** Nested multisig configuration lookup parameters. */
+  export type ResolveConfigOptions = {
+    /** Nested multisig account. */
+    account: Address.Address
+  }
+
+  /** Resolved nested multisig configuration. */
+  export type ResolvedConfig = {
+    /** Current nested multisig configuration. */
+    config: MultisigConfig.Config
+    /** Current nested multisig configuration version. */
+    version: bigint
+  }
+
+  /** Result of validating and selecting approvals. */
+  export type ReturnValue = {
+    /** Every retained approval, ordered by owner address. */
+    approvals: readonly SignatureEnvelope.Serialized[]
+    /** Number of approvals selected for quorum evaluation. */
+    signatureCount: number
+    /** Approvals selected for serialization, ordered by owner address. */
+    selectedApprovals: readonly SignatureEnvelope.Serialized[]
+    /** Required owner weight. */
+    threshold: number
+    /** Owner weight reached by the selected approvals. */
+    weight: number
+  }
+
+  /** Error type for `selectApprovals`. */
+  export type ErrorType =
+    | InvalidApprovalError
+    | MultisigConfig.assert.ErrorType
+    | MultisigConfig.getSignPayload.ErrorType
+    | SignatureEnvelope.CoercionError
+    | SignatureEnvelope.extractAddress.ErrorType
+    | SignatureEnvelope.serialize.ErrorType
+    | SignatureEnvelope.VerificationError
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Serializes a multisig transaction operation with selected owner approvals.
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { MultisigOperation } from 'ox/tempo'
+ *
+ * const transaction = MultisigOperation.serializeTransaction(operation, {
+ *   approvals: selection.selectedApprovals,
+ * })
+ * ```
+ *
+ * @param operation - Multisig transaction operation.
+ * @param options - Transaction serialization options.
+ * @returns The signed serialized Tempo transaction.
+ */
+export function serializeTransaction(
+  operation: TransactionOperation,
+  options: serializeTransaction.Options,
+): TxEnvelopeTempo.Serialized {
+  const value = from(operation)
+  const envelope = TxEnvelopeTempo.deserialize(
+    value.transaction as TxEnvelopeTempo.Serialized,
+  )
+  const approvals = options.approvals.map((approval) =>
+    SignatureEnvelope.from(approval),
+  )
+  assertRetainedApprovals(value, approvals)
+  const signatures = SignatureEnvelope.sortMultisigApprovals({
+    account: value.account,
+    config: value.config,
+    payload: TxEnvelopeTempo.getSignPayload(envelope),
+    signatures: approvals,
+  })
+  const signature = SignatureEnvelope.from({
+    account: value.account,
+    config: value.config,
+    signatures,
+  })
+  return TxEnvelopeTempo.serialize(
+    envelope,
+    value.transaction.startsWith(TxEnvelopeTempo.feePayerMagic)
+      ? {
+          format: 'feePayer',
+          sender: envelope.from,
+          signature,
+        }
+      : { signature },
+  )
+}
+
+export declare namespace serializeTransaction {
+  /** Options for `serializeTransaction`. */
+  export type Options = {
+    /** Selected retained approvals to attach to the transaction. */
+    approvals: readonly SignatureEnvelope.Serialized[]
+  }
+
+  /** Error type for `serializeTransaction`. */
+  export type ErrorType =
+    | from.ErrorType
+    | InvalidOperationError
+    | SignatureEnvelope.sortMultisigApprovals.ErrorType
+    | TxEnvelopeTempo.deserialize.ErrorType
+    | TxEnvelopeTempo.getSignPayload.ErrorType
+    | TxEnvelopeTempo.serialize.ErrorType
+    | Errors.GlobalErrorType
+}
+
 /**
  * Validates and normalizes a multisig operation.
  *
@@ -94,7 +338,10 @@ export function from<const operation extends Operation>(
   operation: operation,
 ): from.ReturnValue<operation> {
   try {
-    const config = MultisigConfig.from(operation.config)
+    const config = MultisigConfig.from({
+      ...operation.config,
+      version: operation.configVersion,
+    })
     if (
       typeof config.threshold !== 'number' ||
       config.owners.some((owner) => typeof owner.weight !== 'number')
@@ -102,12 +349,13 @@ export function from<const operation extends Operation>(
       throw new InvalidOperationError({
         reason: 'config threshold and owner weights must be numbers',
       })
-    assertBase(operation, config)
-    if (operation.type === 'transaction') assertTransaction(operation)
-    else if (operation.type === 'keyAuthorization')
-      assertKeyAuthorization(operation, config)
+    const value = { ...operation, config } as Operation
+    assertBase(value, config)
+    if (value.type === 'transaction') assertTransaction(value)
+    else if (value.type === 'keyAuthorization')
+      assertKeyAuthorization(value, config)
     else throw new InvalidOperationError({ reason: 'unknown operation type' })
-    return { ...operation, config } as never
+    return value as never
   } catch (cause) {
     if (cause instanceof InvalidOperationError) throw cause
     throw new InvalidOperationError({ cause })
@@ -155,7 +403,11 @@ export function fromRpc<const operation extends Rpc>(
       throw new InvalidOperationError({
         reason: 'configVersion must use canonical quantity encoding',
       })
-    return from({ ...operation, configVersion } as Operation) as never
+    return from({
+      ...operation,
+      config: MultisigConfig.fromRpc(operation.config),
+      configVersion,
+    } as Operation) as never
   } catch (cause) {
     if (cause instanceof InvalidOperationError) throw cause
     throw new InvalidOperationError({ cause })
@@ -193,6 +445,7 @@ export function toRpc<const operation extends Operation>(
   const value = from(operation)
   return {
     ...value,
+    config: MultisigConfig.toRpc(value.config),
     configVersion: Hex.fromNumber(value.configVersion),
   } as never
 }
@@ -208,6 +461,222 @@ export declare namespace toRpc {
   export type ErrorType = from.ErrorType | Hex.fromNumber.ErrorType
 }
 
+/**
+ * Validates and selects approvals recursively.
+ *
+ * @internal
+ */
+async function selectApprovals_internal(
+  options: selectApprovals.Options,
+  path: readonly string[],
+): Promise<selectApprovals.ReturnValue> {
+  const owners = new Map(
+    options.config.owners.map((owner) => [
+      owner.owner.toLowerCase(),
+      { address: owner.owner, weight: Number(owner.weight) },
+    ]),
+  )
+  const groups = new Map<string, ApprovalGroup>()
+  for (const serialized of options.approvals) {
+    const signature = SignatureEnvelope.from(serialized)
+    if (signature.type === 'keychain')
+      throw new InvalidApprovalError({
+        reason: 'keychain signatures cannot approve a multisig operation',
+      })
+    const address =
+      signature.type === 'multisig'
+        ? signature.account
+        : SignatureEnvelope.extractAddress({
+            payload: options.hash,
+            signature,
+          })
+    const owner = owners.get(address.toLowerCase())
+    if (!owner)
+      throw new InvalidApprovalError({
+        reason: `signature is from non-owner ${address}`,
+      })
+    const key = address.toLowerCase()
+    const group = groups.get(key)
+    if (group) group.signatures.push(signature)
+    else
+      groups.set(key, {
+        address: owner.address,
+        signatures: [signature],
+        weight: owner.weight,
+      })
+  }
+
+  const valid: SelectedApproval[] = []
+  const retained: RetainedApproval[] = []
+  for (const group of groups.values()) {
+    const nested = group.signatures.filter(
+      (signature) => signature.type === 'multisig',
+    )
+    if (nested.length > 0) {
+      if (nested.length !== group.signatures.length)
+        throw new InvalidApprovalError({
+          reason: `owner ${group.address} has conflicting signature types`,
+        })
+      if (
+        path.length >= MultisigConfig.maxNestingDepth ||
+        path.includes(group.address.toLowerCase())
+      )
+        throw new InvalidApprovalError({
+          reason: `nested multisig owner ${group.address} is invalid`,
+        })
+      if (!options.resolveConfig)
+        throw new InvalidApprovalError({
+          reason: `nested multisig owner ${group.address} requires a config resolver`,
+        })
+      const resolved = await options.resolveConfig({ account: group.address })
+      const config = MultisigConfig.from({
+        ...resolved.config,
+        version: resolved.version,
+      })
+      const selected = await selectApprovals_internal(
+        {
+          account: group.address,
+          approvals: nested.flatMap((signature) =>
+            signature.signatures.map((approval) =>
+              SignatureEnvelope.serialize(approval),
+            ),
+          ),
+          config,
+          hash: MultisigConfig.getSignPayload({
+            account: group.address,
+            config,
+            payload: options.hash,
+          }),
+          resolveConfig: options.resolveConfig,
+        },
+        [...path, group.address.toLowerCase()],
+      )
+      retained.push({
+        address: group.address,
+        signature: SignatureEnvelope.serialize(
+          SignatureEnvelope.from({
+            account: group.address,
+            config,
+            signatures: selected.approvals.map((approval) =>
+              SignatureEnvelope.from(approval),
+            ),
+          }),
+        ),
+      })
+      if (selected.weight >= selected.threshold)
+        valid.push({
+          address: group.address,
+          signature: SignatureEnvelope.serialize(
+            SignatureEnvelope.from({
+              account: group.address,
+              config,
+              signatures: selected.selectedApprovals.map((approval) =>
+                SignatureEnvelope.from(approval),
+              ),
+            }),
+          ),
+          weight: group.weight,
+        })
+      continue
+    }
+
+    const signatures = group.signatures.map((signature) => {
+      if (
+        !SignatureEnvelope.verify(signature, {
+          address: group.address,
+          payload: options.hash,
+        })
+      )
+        throw new InvalidApprovalError({
+          reason: `signature from owner ${group.address} is invalid`,
+        })
+      return SignatureEnvelope.serialize(signature)
+    })
+    const signature = signatures.sort(compareHex)[0]!
+    valid.push({
+      address: group.address,
+      signature,
+      weight: group.weight,
+    })
+    retained.push({ address: group.address, signature })
+  }
+
+  const ranked = valid.sort(
+    (a, b) => b.weight - a.weight || compareApprovalAddress(a, b),
+  )
+  const selected: typeof ranked = []
+  let weight = 0
+  for (const approval of ranked.slice(0, MultisigConfig.maxSignatures)) {
+    if (weight >= Number(options.config.threshold)) break
+    selected.push(approval)
+    weight += approval.weight
+  }
+  selected.sort(compareApprovalAddress)
+
+  return {
+    approvals: retained
+      .sort(compareApprovalAddress)
+      .map((approval) => approval.signature),
+    selectedApprovals: selected.map((approval) => approval.signature),
+    signatureCount: selected.length,
+    threshold: Number(options.config.threshold),
+    weight,
+  }
+}
+
+/** Approval selected for quorum evaluation. @internal */
+type SelectedApproval = {
+  /** Configured owner address. */
+  address: Address.Address
+  /** Serialized owner signature. */
+  signature: SignatureEnvelope.Serialized
+  /** Configured owner weight. */
+  weight: number
+}
+
+/** Approvals submitted for one configured owner. @internal */
+type ApprovalGroup = {
+  /** Configured owner address. */
+  address: Address.Address
+  /** Submitted signatures that resolve to the owner. */
+  signatures: SignatureEnvelope.SignatureEnvelope[]
+  /** Configured owner weight. */
+  weight: number
+}
+
+/** Approval retained in operation storage. @internal */
+type RetainedApproval = {
+  /** Configured owner address. */
+  address: Address.Address
+  /** Serialized primitive or normalized nested approval. */
+  signature: SignatureEnvelope.Serialized
+}
+
+/**
+ * Orders approval records by owner address.
+ *
+ * @internal
+ */
+function compareApprovalAddress(
+  a: SelectedApproval | RetainedApproval,
+  b: SelectedApproval | RetainedApproval,
+) {
+  const addressA = Hex.toBigInt(a.address)
+  const addressB = Hex.toBigInt(b.address)
+  return addressA < addressB ? -1 : addressA > addressB ? 1 : 0
+}
+
+/**
+ * Orders hexadecimal data bytewise.
+ *
+ * @internal
+ */
+function compareHex(a: Hex.Hex, b: Hex.Hex) {
+  const hexA = a.toLowerCase()
+  const hexB = b.toLowerCase()
+  return hexA < hexB ? -1 : hexA > hexB ? 1 : 0
+}
+
 /**
  * Validates fields shared by every operation.
  *
@@ -276,6 +745,7 @@ function assertBase(operation: Operation, config: MultisigConfig.Config): void {
     const signature = assertApproval(
       operation.account,
       approval as SignatureEnvelope.Serialized,
+      config,
     )
     const address = SignatureEnvelope.extractAddress({
       payload: operation.hash,
@@ -481,13 +951,9 @@ function assertKeyAuthorization(
         reason: 'key authorization signatureCount does not match its signature',
       })
     assertSelectedApprovals(operation, signature.signatures, authorization)
-    if (!!signature.init !== operation.init)
+    if (!sameConfig(signature.config, config))
       throw new InvalidOperationError({
-        reason: 'key authorization bootstrap state does not match',
-      })
-    if (signature.init && !sameConfig(signature.init, config))
-      throw new InvalidOperationError({
-        reason: 'key authorization bootstrap config does not match',
+        reason: 'key authorization config does not match',
       })
   }
   assertOperationHash(
@@ -511,10 +977,12 @@ function assertKeyAuthorization(
 function assertApproval(
   account: Address.Address,
   serialized: SignatureEnvelope.Serialized,
+  config: MultisigConfig.Config,
 ): SignatureEnvelope.SignatureEnvelope {
   const approval = SignatureEnvelope.deserialize(serialized)
   SignatureEnvelope.assert({
     account,
+    config,
     signatures: [approval],
     type: 'multisig',
   })
@@ -526,6 +994,30 @@ function assertApproval(
   return approval
 }
 
+/**
+ * Checks that selected transaction approvals are retained by the operation.
+ *
+ * @internal
+ */
+function assertRetainedApprovals(
+  operation: TransactionOperation,
+  selected: readonly SignatureEnvelope.SignatureEnvelope[],
+): void {
+  const retained = operation.approvals.map((approval) =>
+    SignatureEnvelope.deserialize(approval),
+  )
+  for (const approval of selected) {
+    const index = retained.findIndex((candidate) =>
+      includesApproval(candidate, approval),
+    )
+    if (index === -1)
+      throw new InvalidOperationError({
+        reason: 'transaction signature is not a retained approval',
+      })
+    retained.splice(index, 1)
+  }
+}
+
 /**
  * Checks that a successful key authorization uses retained approvals in canonical order.
  *
@@ -552,8 +1044,8 @@ function assertSelectedApprovals(
 
   const digest = MultisigConfig.getSignPayload({
     account: operation.account,
+    config: operation.config,
     payload: KeyAuthorization_.getSignPayload(authorization),
-    version: operation.configVersion,
   })
   const addresses = selected.map((signature) =>
     SignatureEnvelope.extractAddress({ payload: digest, signature }),
@@ -588,7 +1080,7 @@ function includesApproval(
     )
   if (retained.account.toLowerCase() !== selected.account.toLowerCase())
     return false
-  // Nested versions are not serialized, so selected child approvals must preserve the validated retained order.
+  if (!sameConfig(retained.config, selected.config)) return false
   let index = 0
   for (const approval of selected.signatures) {
     while (
@@ -632,8 +1124,8 @@ function isWeightReachable(
 function assertOperationHash(operation: Operation, payload: Hex.Hex): void {
   const hash = MultisigConfig.getSignPayload({
     account: operation.account,
+    config: operation.config,
     payload,
-    version: operation.configVersion,
   })
   if (hash.toLowerCase() !== operation.hash.toLowerCase())
     throw new InvalidOperationError({
@@ -670,6 +1162,7 @@ function sameConfig(
       configB.salt ?? MultisigConfig.zeroSalt,
     ) &&
     configA.threshold === configB.threshold &&
+    configA.version === configB.version &&
     configA.owners.length === configB.owners.length &&
     configA.owners.every((owner, index) => {
       const other = configB.owners[index]!
@@ -681,6 +1174,44 @@ function sameConfig(
   )
 }
 
+/** Thrown when a multisig owner approval is invalid. */
+export class InvalidApprovalError extends Errors.BaseError<Error | undefined> {
+  override readonly name = 'MultisigOperation.InvalidApprovalError'
+
+  /**
+   * Creates an invalid multisig approval error.
+   *
+   * @example
+   * ```ts twoslash
+   * import { MultisigOperation } from 'ox/tempo'
+   *
+   * throw new MultisigOperation.InvalidApprovalError({
+   *   reason: 'signature is from a non-owner',
+   * })
+   * ```
+   *
+   * @param options - Error options.
+   */
+  constructor(options: InvalidApprovalError.Options = {}) {
+    super(
+      options.reason
+        ? `Invalid multisig approval: ${options.reason}.`
+        : 'Invalid multisig approval.',
+      { cause: options.cause as Error | undefined },
+    )
+  }
+}
+
+export declare namespace InvalidApprovalError {
+  /** Error construction options. */
+  export type Options = {
+    /** Underlying error. */
+    cause?: unknown | undefined
+    /** Validation failure. */
+    reason?: string | undefined
+  }
+}
+
 /** Thrown when a multisig operation is malformed or internally inconsistent. */
 export class InvalidOperationError extends Errors.BaseError<Error | undefined> {
   override readonly name = 'MultisigOperation.InvalidOperationError'