ox 0.14.44 → 0.14.46

package/tempo/KeyAuthorization.ts

@@ -3,7 +3,11 @@ import type * as Address from '../core/Address.js'
 import type * as Errors from '../core/Errors.js'
 import * as Hash from '../core/Hash.js'
 import * as Hex from '../core/Hex.js'
-import type { Compute, OneOf, UnionPartialBy } from '../core/internal/types.js'
+import type {
+  Compute,
+  PartialBy,
+  UnionPartialBy,
+} from '../core/internal/types.js'
 import * as Rlp from '../core/Rlp.js'
 import * as SignatureEnvelope from './SignatureEnvelope.js'
 import * as TempoAddress from './TempoAddress.js'
@@ -25,7 +29,7 @@ import * as TempoAddress from './TempoAddress.js'
  * - `chainId`: Chain ID for replay protection (0 = valid on any chain)
  * - `expiry`: Unix timestamp when the key expires (undefined = never expires)
  * - `limits`: Per-TIP-20 token spending limits (only applies to `transfer()` and `approve()` calls)
- * - `type`: Key type (`secp256k1`, `p256`, or `webAuthn`)
+ * - `type`: Key type (`secp256k1`, `p256`, `webAuthn`, or `multisig`)
  *
  * [Access Keys Specification](https://docs.tempo.xyz/protocol/transactions/spec-tempo-transaction#access-keys)
  */
@@ -41,6 +45,8 @@ export type KeyAuthorization<
   chainId: bigintType
   /** Unix timestamp when key expires (undefined = never expires). */
   expiry?: numberType | null | undefined
+  /** Whether this authorization provisions an admin access key. */
+  isAdmin?: boolean | undefined
   /** TIP20 spending limits for this key. */
   limits?:
     | readonly TokenLimit<bigintType, numberType, addressType>[]
@@ -53,8 +59,6 @@ export type KeyAuthorization<
    * - `[...]` = only listed contract+selector combinations allowed
    */
   scopes?: readonly Scope<addressType>[] | undefined
-  /** Key type. (secp256k1, P256, WebAuthn). */
-  type: SignatureEnvelope.Type
   /**
    * Optional 32-byte witness bound into the signing hash.
    *
@@ -65,32 +69,37 @@ export type KeyAuthorization<
    * [TIP-1053 Specification](https://tips.sh/1053)
    */
   witness?: Hex.Hex | undefined
-} & OneOf<
-  // TIP-1049 admin access keys: `account` and `isAdmin` are paired — either
-  // both are specified or neither. The `account` binding scopes the signing
-  // hash to a specific account, and `isAdmin: true` provisions an admin
-  // access key with unrestricted keychain mutator privileges.
-  //
-  // [TIP-1049 Specification](https://tips.sh/1049)
+} & (
+  | {
+      /** Optional account address binding. */
+      account?: addressType | undefined
+      /** Primitive key type. */
+      type: SignatureEnvelope.Type
+    }
   | {
-      /** Account address this authorization is bound to. */
+      /** Required parent account binding for a multisig grant. */
       account: addressType
-      /** Whether this authorization provisions an admin access key. */
-      isAdmin: boolean
+      /** Multisig key type. */
+      type: 'multisig'
     }
-  | {}
-> &
+) &
   (signed extends true
-    ? { signature: Signature<bigintType, numberType> }
+    ? {
+        signature:
+          | SignatureEnvelope.Primitive<bigintType, numberType>
+          | SignatureEnvelope.Multisig<bigintType, numberType>
+      }
     : {
-        signature?: Signature<bigintType, numberType> | undefined
+        signature?:
+          | SignatureEnvelope.Primitive<bigintType, numberType>
+          | SignatureEnvelope.Multisig<bigintType, numberType>
+          | undefined
       })
 
 /** Signature that can authorize an access key. */
-export type Signature<bigintType = bigint, numberType = number> = OneOf<
+export type Signature<bigintType = bigint, numberType = number> =
   | SignatureEnvelope.Primitive<bigintType, numberType>
   | SignatureEnvelope.Multisig<bigintType, numberType>
->
 
 /** RPC-formatted signature that can authorize an access key. */
 export type SignatureRpc =
@@ -107,8 +116,6 @@ export type Input = KeyAuthorization<
 
 /** RPC representation matching the node's wire format. */
 export type Rpc = {
-  /** Optional account address binding (TIP-1049). */
-  account?: Address.Address | null | undefined
   /** Allowed call scopes (node field: `allowedCalls`). */
   allowedCalls?: readonly RpcCallScope[] | undefined
   /** Chain ID (hex quantity). */
@@ -119,33 +126,44 @@ export type Rpc = {
   isAdmin?: boolean | null | undefined
   /** Key identifier. */
   keyId: Address.Address
-  /** Key type. */
-  keyType: SignatureEnvelope.Type
   /** Token spending limits. */
   limits?: readonly RpcTokenLimit[] | undefined
   /** Signature authorizing this key. */
   signature: SignatureRpc
   /** Optional 32-byte witness (hex). */
   witness?: Hex.Hex | null | undefined
-}
+} & (
+  | {
+      /** Optional account address binding (TIP-1049). */
+      account?: Address.Address | null | undefined
+      /** Primitive key type. */
+      keyType: SignatureEnvelope.Type
+    }
+  | {
+      /** Required parent account binding for a multisig grant. */
+      account: Address.Address
+      /** Multisig key type. */
+      keyType: 'multisig'
+    }
+)
 
 /** RPC representation of a token limit (matches node's `TokenLimit` serde). */
 export type RpcTokenLimit = {
-  token: Address.Address
   limit: Hex.Hex
   period?: Hex.Hex | undefined
+  token: Address.Address
 }
 
 /** RPC representation of a call scope (matches node's `CallScope` serde). */
 export type RpcCallScope = {
+  selectorRules?: readonly RpcSelectorRule[] | undefined
   target: Address.Address
-  selectorRules?: readonly RpcSelectorRule[]
 }
 
 /** RPC representation of a selector rule (matches node's `SelectorRule` serde). */
 export type RpcSelectorRule = {
+  recipients?: readonly Address.Address[] | undefined
   selector: Hex.Hex
-  recipients?: readonly Address.Address[]
 }
 
 /** Signed representation of a Key Authorization. */
@@ -156,10 +174,11 @@ export type Signed<
 > = KeyAuthorization<true, bigintType, numberType, addressType>
 
 type SignatureValue =
-  | UnionPartialBy<Signature, 'prehash' | 'type'>
+  | SignatureEnvelope.from.MultisigFromConfig
+  | UnionPartialBy<SignatureEnvelope.Primitive, 'prehash' | 'type'>
+  | PartialBy<SignatureEnvelope.Multisig, 'type'>
   | SignatureEnvelope.Secp256k1Flat
   | SignatureEnvelope.Serialized
-  | SignatureEnvelope.from.MultisigFromConfig
 
 type BaseTuple = readonly [
   chainId: Hex.Hex,
@@ -235,14 +254,6 @@ export type Tuple<signed extends boolean = boolean> = signed extends true
 export type Scope<addressType = Address.Address> = {
   /** Target contract address. */
   address: addressType
-  /**
-   * 4-byte function selector, or a human-readable ABI signature
-   * (e.g. `'transfer(address,uint256)'` or `'function transfer(address,uint256)'`).
-   *
-   * Signatures are encoded into a 4-byte selector automatically.
-   * Omit to allow any selector on this contract.
-   */
-  selector?: Hex.Hex | string | undefined
   /**
    * Recipient allowlist for this selector (first ABI `address` argument).
    *
@@ -252,6 +263,8 @@ export type Scope<addressType = Address.Address> = {
    * Only valid for constrained selectors: `transfer`, `approve`, `transferWithMemo`.
    */
   recipients?: readonly addressType[] | undefined
+  /** Function selector or human-readable ABI signature. */
+  selector?: Hex.Hex | string | undefined
 }
 
 /**
@@ -267,8 +280,6 @@ export type TokenLimit<
   numberType = number,
   addressType = Address.Address,
 > = {
-  /** Address of the TIP-20 token. */
-  token: addressType
   /** Maximum spending amount for this token (enforced over the key's lifetime, or per period if `period` \> 0). */
   limit: bigintType
   /**
@@ -278,6 +289,8 @@ export type TokenLimit<
    * - `\> 0` = periodic limit that resets every `period` seconds
    */
   period?: numberType | undefined
+  /** Address of the TIP-20 token. */
+  token: addressType
 }
 
 /**
@@ -424,6 +437,7 @@ export function from<
   options: from.Options<signature> = {},
 ): from.ReturnType<authorization, signature> {
   if ('keyId' in authorization) return fromRpc(authorization as Rpc) as never
+  assertAccountBinding(authorization.type, authorization.account)
   const auth = authorization as KeyAuthorization & {
     limits?: readonly { token: TempoAddress.Address; limit: bigint }[]
     scopes?: readonly {
@@ -436,6 +450,9 @@ export function from<
   if (auth.signature) assertSignature(auth.signature)
   const resolved = {
     ...auth,
+    ...(auth.account !== undefined
+      ? { account: TempoAddress.resolve(auth.account) }
+      : {}),
     address: TempoAddress.resolve(auth.address as TempoAddress.Address),
     ...(auth.limits
       ? {
@@ -479,8 +496,12 @@ export declare namespace from {
   type Options<
     signature extends SignatureValue | undefined = SignatureValue | undefined,
   > = {
-    /** The signature to attach to the Key Authorization. */
-    signature?: signature | Signature | undefined
+    /** The primitive or multisig signature to attach to the Key Authorization. */
+    signature?:
+      | signature
+      | SignatureEnvelope.Primitive
+      | SignatureEnvelope.Multisig
+      | undefined
   }
 
   type ReturnType<
@@ -502,7 +523,10 @@ export declare namespace from {
         >
   >
 
-  type ErrorType = InvalidSignatureTypeError | Errors.GlobalErrorType
+  type ErrorType =
+    | InvalidSignatureTypeError
+    | MissingAccountError
+    | Errors.GlobalErrorType
 }
 
 /**
@@ -536,6 +560,7 @@ export function fromRpc(authorization: Rpc): Signed {
   const witness = authorization.witness ?? undefined
   const isAdmin = authorization.isAdmin ?? undefined
   const account = authorization.account ?? undefined
+  assertAccountBinding(keyType, account)
   const signature = SignatureEnvelope.fromRpc(authorization.signature)
   assertSignature(signature)
   if (witness !== undefined) assertWitness(witness)
@@ -557,9 +582,6 @@ export function fromRpc(authorization: Rpc): Signed {
       })
     : undefined
 
-  const accountBinding =
-    account !== undefined ? { account, isAdmin: isAdmin ?? false } : {}
-
   return {
     address: keyId,
     chainId: chainId === '0x' ? 0n : Hex.toBigInt(chainId),
@@ -573,14 +595,20 @@ export function fromRpc(authorization: Rpc): Signed {
     })),
     ...(scopes ? { scopes } : {}),
     signature,
-    type: keyType,
+    ...(keyType === 'multisig'
+      ? { account: account!, type: keyType }
+      : { type: keyType }),
     ...(witness !== undefined ? { witness } : {}),
-    ...accountBinding,
+    ...(account !== undefined ? { account } : {}),
+    ...(isAdmin ? { isAdmin: true as const } : {}),
   }
 }
 
 export declare namespace fromRpc {
-  type ErrorType = InvalidSignatureTypeError | Errors.GlobalErrorType
+  type ErrorType =
+    | InvalidSignatureTypeError
+    | MissingAccountError
+    | Errors.GlobalErrorType
 }
 
 /**
@@ -642,6 +670,8 @@ export function fromTuple<const tuple extends Tuple>(
         return 'p256'
       case '0x02':
         return 'webAuthn'
+      case '0x03':
+        return 'multisig'
       default:
         throw new Error(`Invalid key type: ${keyType_hex}`)
     }
@@ -697,17 +727,19 @@ export function fromTuple<const tuple extends Tuple>(
   const account = isAbsent(rawAccount)
     ? undefined
     : (rawAccount as Address.Address)
-  const accountBinding =
-    account !== undefined ? { account, isAdmin: isAdmin ?? false } : {}
+  assertAccountBinding(keyType, account)
   const args: KeyAuthorization = {
     address: keyId,
     chainId: chainId === '0x' ? 0n : Hex.toBigInt(chainId),
-    type: keyType,
+    ...(keyType === 'multisig'
+      ? { account: account!, type: keyType }
+      : { type: keyType }),
     ...(expiry !== undefined ? { expiry } : {}),
     ...(limits !== undefined ? { limits } : {}),
     ...(scopes !== undefined ? { scopes } : {}),
     ...(witness !== undefined ? { witness } : {}),
-    ...accountBinding,
+    ...(account !== undefined ? { account } : {}),
+    ...(isAdmin ? { isAdmin: true as const } : {}),
   }
   if (signatureSerialized) {
     const signature = SignatureEnvelope.deserialize(signatureSerialized)
@@ -722,7 +754,10 @@ export declare namespace fromTuple {
     KeyAuthorization<authorization extends Tuple<true> ? true : false>
   >
 
-  type ErrorType = InvalidSignatureTypeError | Errors.GlobalErrorType
+  type ErrorType =
+    | InvalidSignatureTypeError
+    | MissingAccountError
+    | Errors.GlobalErrorType
 }
 
 /**
@@ -914,6 +949,7 @@ export declare namespace serialize {
  * @returns An RPC-formatted Key Authorization.
  */
 export function toRpc(authorization: Signed): Rpc {
+  assertAccountBinding(authorization.type, authorization.account)
   const {
     address,
     scopes,
@@ -957,13 +993,15 @@ export function toRpc(authorization: Signed): Rpc {
     chainId: chainId === 0n ? '0x' : Hex.fromNumber(chainId),
     expiry: typeof expiry === 'number' ? Hex.fromNumber(expiry) : null,
     keyId: TempoAddress.resolve(address),
-    keyType: type,
+    ...(type === 'multisig' ? { account, keyType: type } : { keyType: type }),
     limits: limits?.map(({ token, limit, period }) => ({
       token,
       limit: Hex.fromNumber(limit),
       ...(period ? { period: numberToHex(period) } : {}),
     })),
-    signature: SignatureEnvelope.toRpc(signature) as SignatureRpc,
+    signature: SignatureEnvelope.toRpc(signature) as
+      | SignatureEnvelope.PrimitiveRpc
+      | SignatureEnvelope.MultisigRpc,
     ...(allowedCalls ? { allowedCalls } : {}),
     ...(witness !== undefined ? { witness } : {}),
     ...(isAdmin ? { isAdmin: true } : {}),
@@ -972,7 +1010,10 @@ export function toRpc(authorization: Signed): Rpc {
 }
 
 export declare namespace toRpc {
-  type ErrorType = InvalidSignatureTypeError | Errors.GlobalErrorType
+  type ErrorType =
+    | InvalidSignatureTypeError
+    | MissingAccountError
+    | Errors.GlobalErrorType
 }
 
 /**
@@ -1009,6 +1050,7 @@ export declare namespace toRpc {
 export function toTuple<const authorization extends KeyAuthorization>(
   authorization: authorization,
 ): toTuple.ReturnType<authorization> {
+  assertAccountBinding(authorization.type, authorization.account)
   const {
     address,
     chainId,
@@ -1025,16 +1067,19 @@ export function toTuple<const authorization extends KeyAuthorization>(
     assertSignature(authorization.signature)
     return SignatureEnvelope.serialize(authorization.signature)
   })()
+  const keyType = authorization.type
   const type = (() => {
-    switch (authorization.type) {
+    switch (keyType) {
       case 'secp256k1':
         return '0x'
       case 'p256':
         return '0x01'
       case 'webAuthn':
         return '0x02'
+      case 'multisig':
+        return '0x03'
       default:
-        throw new Error(`Invalid key type: ${authorization.type}`)
+        throw new Error(`Invalid key type: ${keyType}`)
     }
   })()
   const limitsValue = limits?.map((limit) => {
@@ -1083,7 +1128,7 @@ export function toTuple<const authorization extends KeyAuthorization>(
   // single entry to this list with `placeholder: '0x'`.
   const hasTip1053Plus =
     witness !== undefined || isAdmin || account !== undefined
-  const optionals: readonly { value: unknown; placeholder: unknown }[] = [
+  const optionals: readonly { placeholder: unknown; value: unknown }[] = [
     {
       value:
         expiry !== null && expiry !== undefined && expiry !== 0
@@ -1120,7 +1165,10 @@ export declare namespace toTuple {
   type ReturnType<authorization extends KeyAuthorization = KeyAuthorization> =
     Compute<Tuple<authorization extends KeyAuthorization<true> ? true : false>>
 
-  type ErrorType = InvalidSignatureTypeError | Errors.GlobalErrorType
+  type ErrorType =
+    | InvalidSignatureTypeError
+    | MissingAccountError
+    | Errors.GlobalErrorType
 }
 
 function bigintToHex(value: bigint): Hex.Hex {
@@ -1154,6 +1202,13 @@ function resolveSelector(
   return AbiItem.getSelector(selector)
 }
 
+function assertAccountBinding(
+  type: KeyAuthorization['type'],
+  account: TempoAddress.Address | null | undefined,
+): void {
+  if (type === 'multisig' && account == null) throw new MissingAccountError()
+}
+
 function assertWitness(witness: Hex.Hex): void {
   if (Hex.size(witness) !== 32) throw new InvalidWitnessSizeError(witness)
 }
@@ -1198,3 +1253,11 @@ export class InvalidSignatureTypeError extends Error {
     )
   }
 }
+
+/** Thrown when a multisig key grant omits its parent account binding. */
+export class MissingAccountError extends Error {
+  override readonly name = 'KeyAuthorization.MissingAccountError'
+  constructor() {
+    super('Multisig key grants require a parent account binding.')
+  }
+}

package/tempo/MultisigConfig.test.ts

@@ -1,6 +1,7 @@
 import { Hash, Hex, Rlp } from 'ox'
 import { MultisigConfig } from 'ox/tempo'
 import { describe, expect, test } from 'vitest'
+import { factory } from '../../test/tempo/multisig.js'
 
 const owner_1 = '0x1111111111111111111111111111111111111111'
 const owner_2 = '0x2222222222222222222222222222222222222222'
@@ -9,7 +10,7 @@ const config = MultisigConfig.from({
   owners: [{ owner: owner_1, weight: 1 }],
   threshold: 1,
 })
-const account = MultisigConfig.getAddress(config)
+const account = MultisigConfig.getAddress(config, { factory })
 
 describe('from', () => {
   test('behavior: normalizes an initial configuration', () => {
@@ -101,49 +102,57 @@ describe('fromRpc/toRpc', () => {
 describe('getAddress', () => {
   test('example: matches the frozen CREATE2 vector', () => {
     expect(account).toMatchInlineSnapshot(
-      `"0xf4b916c5aea0fb199bd942389be00db0690c961f"`,
+      `"0x90ba71cb7534da990a1182cf28c9bf415055e03d"`,
     )
     expect(account).not.toBe('0x8820d1497eeaf4f68e00b2cfc00a2f3b1dbb00da')
   })
 
   test('behavior: includes salt, threshold, and owners', () => {
     expect(
-      MultisigConfig.getAddress({
-        owners: [
-          { owner: owner_1, weight: 1 },
-          { owner: owner_2, weight: 2 },
-        ],
-        salt: `0x${'42'.repeat(32)}`,
-        threshold: 2,
-      }),
-    ).toMatchInlineSnapshot(`"0x94040edd3d7b542e0a96e01141bc250d709b4469"`)
+      MultisigConfig.getAddress(
+        {
+          owners: [
+            { owner: owner_1, weight: 1 },
+            { owner: owner_2, weight: 2 },
+          ],
+          salt: `0x${'42'.repeat(32)}`,
+          threshold: 2,
+        },
+        { factory },
+      ),
+    ).toMatchInlineSnapshot(`"0x7898a7d1dd96946d2a968de1540ca884a244320c"`)
   })
 
   test('behavior: is stable and binds the salt', () => {
     expect({
-      repeated: MultisigConfig.getAddress(config),
-      salted: MultisigConfig.getAddress({
-        ...config,
-        salt: `0x${'42'.repeat(32)}`,
-      }),
+      repeated: MultisigConfig.getAddress(config, { factory }),
+      salted: MultisigConfig.getAddress(
+        {
+          ...config,
+          salt: `0x${'42'.repeat(32)}`,
+        },
+        { factory },
+      ),
     }).toMatchInlineSnapshot(`
       {
-        "repeated": "0xf4b916c5aea0fb199bd942389be00db0690c961f",
-        "salted": "0x95e771f514fd6ac5b8bbd62a9b37db86eeed7e38",
+        "repeated": "0x90ba71cb7534da990a1182cf28c9bf415055e03d",
+        "salted": "0xa1a8472f4a01772db729d8ebc73fe46120750b83",
       }
     `)
   })
 
   test('error: rejects a current configuration', () => {
     expect(() =>
-      MultisigConfig.getAddress({ ...config, version: 1n }),
+      MultisigConfig.getAddress({ ...config, version: 1n }, { factory }),
     ).toThrowErrorMatchingInlineSnapshot(
       `[MultisigConfig.InvalidConfigError: Invalid native multisig config: account address requires version zero.]`,
     )
   })
 
   test('behavior: accepts numeric zero for an initial configuration', () => {
-    expect(MultisigConfig.getAddress({ ...config, version: 0 })).toBe(account)
+    expect(
+      MultisigConfig.getAddress({ ...config, version: 0 }, { factory }),
+    ).toBe(account)
   })
 })
 
@@ -168,7 +177,7 @@ describe('getSignPayload', () => {
     expect(
       MultisigConfig.getSignPayload({ account, config, payload }),
     ).toMatchInlineSnapshot(
-      `"0xdba6b49849aaef399fbc1de73fe26d520f21846c80c3e5d2486ad56e8df3cee3"`,
+      `"0x728efe90611b01c91c2be0da56e7eb8e0d2c274c84f97182e274187dde0b8a20"`,
     )
   })
 
@@ -223,14 +232,14 @@ describe('assert/validate', () => {
     })
     const rlp = Rlp.fromHex(MultisigConfig.toTuple(boundary))
     expect({
-      account: MultisigConfig.getAddress(boundary),
+      account: MultisigConfig.getAddress(boundary, { factory }),
       commitment: MultisigConfig.getCommitment(boundary),
       rlpHash: Hash.keccak256(rlp),
       rlpLength: Hex.size(rlp),
       valid: MultisigConfig.validate(boundary),
     }).toMatchInlineSnapshot(`
       {
-        "account": "0xa832c9a61d254a157c05edcd856b2cbe4dea8c77",
+        "account": "0x6acb25715a2b0cf05c098f753a87d9b38471e99f",
         "commitment": "0x0dc47a7ab45ffa21a01bfd115427e26617b5a57d7ccbea57db2fd4537ba96f56",
         "rlpHash": "0xbaf0d030add91caaa10815d2e99c942f1e39b0d199216973781adb4fc1af6955",
         "rlpLength": 1145,
@@ -246,7 +255,7 @@ describe('assert/validate', () => {
           { owner: owner_1, weight: 128 },
           { owner: owner_2, weight: 127 },
         ],
-        threshold: 255,
+        threshold: 8,
       }),
     ).toBe(true)
   })
@@ -312,7 +321,7 @@ describe('assert/validate', () => {
           { owner: owner_1, weight: 128 },
           { owner: owner_2, weight: 128 },
         ],
-        threshold: 255,
+        threshold: 8,
       },
       name: 'weight overflow',
     },
@@ -359,7 +368,6 @@ describe('assert/validate', () => {
 test('exports', () => {
   expect(Object.keys(MultisigConfig)).toMatchInlineSnapshot(`
     [
-      "maxNestingDepth",
       "maxOwnerSignatureBytes",
       "maxOwners",
       "maxSignatures",