ox 1.6.2 → 1.7.0

package/src/tempo/KeyAuthorization.ts

@@ -78,11 +78,22 @@ export type KeyAuthorization<
   | {}
 > &
   (signed extends true
-    ? { signature: SignatureEnvelope.Primitive<numberType> }
+    ? { signature: Signature<numberType> }
     : {
-        signature?: SignatureEnvelope.Primitive<numberType> | undefined
+        signature?: Signature<numberType> | undefined
       })
 
+/** Signature that can authorize an access key. */
+export type Signature<numberType = number> = OneOf<
+  | SignatureEnvelope.Primitive<numberType>
+  | SignatureEnvelope.Multisig<numberType>
+>
+
+/** RPC-formatted signature that can authorize an access key. */
+export type SignatureRpc = OneOf<
+  SignatureEnvelope.PrimitiveRpc | SignatureEnvelope.MultisigRpc
+>
+
 /** Input type for a Key Authorization. */
 export type Input = KeyAuthorization<false, bigint, number>
 
@@ -104,8 +115,8 @@ export type Rpc = {
   keyType: SignatureEnvelope.Type
   /** Token spending limits. */
   limits?: readonly RpcTokenLimit[] | null | undefined
-  /** Primitive signature authorizing this key. */
-  signature: SignatureEnvelope.PrimitiveRpc
+  /** Signature authorizing this key. */
+  signature: SignatureRpc
   /** Optional 32-byte witness (hex). */
   witness?: Hex.Hex | null | undefined
 }
@@ -136,10 +147,11 @@ export type Signed<bigintType = bigint, numberType = number> = KeyAuthorization<
   numberType
 >
 
-type PrimitiveSignatureValue =
-  | UnionPartialBy<SignatureEnvelope.Primitive, 'prehash' | 'type'>
+type SignatureValue =
+  | UnionPartialBy<Signature, 'prehash' | 'type'>
   | SignatureEnvelope.Secp256k1Flat
   | SignatureEnvelope.Serialized
+  | SignatureEnvelope.from.MultisigFromInitialConfig
 
 type BaseTuple = readonly [
   chainId: Hex.Hex,
@@ -415,7 +427,7 @@ export type TokenLimit<bigintType = bigint, numberType = number> = {
  */
 export function from<
   const authorization extends Input | Rpc,
-  const signature extends PrimitiveSignatureValue | undefined = undefined,
+  const signature extends SignatureValue | undefined = undefined,
 >(
   authorization: authorization | KeyAuthorization,
   options: from.Options<signature> = {},
@@ -457,28 +469,24 @@ export function from<
 
 export declare namespace from {
   type Options<
-    signature extends PrimitiveSignatureValue | undefined =
-      | PrimitiveSignatureValue
-      | undefined,
+    signature extends SignatureValue | undefined = SignatureValue | undefined,
   > = {
-    /** The primitive signature to attach to the Key Authorization. */
-    signature?: signature | SignatureEnvelope.Primitive | undefined
+    /** The signature to attach to the Key Authorization. */
+    signature?: signature | Signature | undefined
   }
 
   type ReturnType<
     authorization extends KeyAuthorization | Input | Rpc = KeyAuthorization,
-    signature extends PrimitiveSignatureValue | undefined =
-      | PrimitiveSignatureValue
-      | undefined,
+    signature extends SignatureValue | undefined = SignatureValue | undefined,
   > = Compute<
     authorization extends Rpc
       ? Signed
       : authorization &
-          (signature extends PrimitiveSignatureValue
+          (signature extends SignatureValue
             ? {
                 signature: Extract<
                   SignatureEnvelope.from.ReturnValue<signature>,
-                  SignatureEnvelope.Primitive
+                  Signature
                 >
               }
             : {})
@@ -544,11 +552,8 @@ export function fromRpc(authorization: Rpc): Signed {
       })
     : undefined
 
-  // TIP-1049 admin fields are paired: emit both or neither; orphan wire
-  // fields are dropped. Separate conditional spreads break `Signed`
-  // assignability without `exactOptionalPropertyTypes` (#290).
-  const adminPair =
-    account !== undefined && isAdmin ? { account, isAdmin: true as const } : {}
+  const accountBinding =
+    account !== undefined ? { account, isAdmin: isAdmin ?? false } : {}
 
   return {
     address: keyId,
@@ -565,7 +570,7 @@ export function fromRpc(authorization: Rpc): Signed {
     signature,
     type: keyType,
     ...(witness !== undefined ? { witness } : {}),
-    ...adminPair,
+    ...accountBinding,
   }
 }
 
@@ -697,11 +702,8 @@ export function fromTuple<const tuple extends Tuple>(
   const account = isAbsent(rawAccount)
     ? undefined
     : (rawAccount as Address.Address)
-  // TIP-1049 admin fields are paired: only emit both when both are present on
-  // the wire. Wire shapes carrying only one are tolerated for forward-compat
-  // but the orphan field is dropped (since the public API requires both).
-  const adminPair =
-    account !== undefined && isAdmin ? { account, isAdmin: true as const } : {}
+  const accountBinding =
+    account !== undefined ? { account, isAdmin: isAdmin ?? false } : {}
   const args: KeyAuthorization = {
     address: keyId,
     chainId: chainId === '0x' ? 0n : Hex.toBigInt(chainId),
@@ -710,7 +712,7 @@ export function fromTuple<const tuple extends Tuple>(
     ...(limits !== undefined ? { limits } : {}),
     ...(scopes !== undefined ? { scopes } : {}),
     ...(witness !== undefined ? { witness } : {}),
-    ...adminPair,
+    ...accountBinding,
   }
   if (signatureSerialized) {
     const signature = SignatureEnvelope.deserialize(signatureSerialized)
@@ -982,9 +984,7 @@ export function toRpc(authorization: toRpc.Input): Rpc {
       limit: Quantity.fromNumberish(limit),
       ...(period ? { period: Quantity.fromNumberish(period) } : {}),
     })),
-    signature: SignatureEnvelope.toRpc(
-      signature,
-    ) as SignatureEnvelope.PrimitiveRpc,
+    signature: SignatureEnvelope.toRpc(signature) as SignatureRpc,
     ...(allowedCalls ? { allowedCalls } : {}),
     ...(witness !== undefined ? { witness } : {}),
     ...(isAdmin ? { isAdmin: true } : {}),
@@ -1186,8 +1186,8 @@ function assertWitness(witness: Hex.Hex): void {
 
 function assertSignature<numberType>(
   signature: SignatureEnvelope.SignatureEnvelope<numberType>,
-): asserts signature is SignatureEnvelope.Primitive<numberType> {
-  if (signature.type === 'keychain' || signature.type === 'multisig')
+): asserts signature is Signature<numberType> {
+  if (signature.type === 'keychain')
     throw new InvalidSignatureTypeError(signature.type)
 }
 
@@ -1215,12 +1215,12 @@ export class InvalidAdminMarkerError extends Error {
   }
 }
 
-/** Thrown when a key authorization contains a non-primitive signature. */
+/** Thrown when a key authorization contains a keychain signature. */
 export class InvalidSignatureTypeError extends Error {
   override readonly name = 'KeyAuthorization.InvalidSignatureTypeError'
   constructor(type: SignatureEnvelope.SignatureEnvelope['type']) {
     super(
-      `Signature type \`${type}\` is invalid for key authorizations; expected \`secp256k1\`, \`p256\`, or \`webAuthn\`.`,
+      `Signature type \`${type}\` is invalid for key authorizations; expected \`secp256k1\`, \`p256\`, \`webAuthn\`, or \`multisig\`.`,
     )
   }
 }

package/src/tempo/MultisigConfig.test.ts

@@ -86,24 +86,44 @@ describe('getSignPayload', () => {
   test('matches independent ground truth', () => {
     expect(
       MultisigConfig.getSignPayload({
-        payload: `0x${'de'.repeat(32)}`,
-        genesisConfig: singleOwnerConfig,
+        payload: `0x${'42'.repeat(32)}`,
+        initialConfig: singleOwnerConfig,
       }),
     ).toMatchInlineSnapshot(
-      `"0x7df8cb9fef4fc2aeb271b617d1a4c6178b720ae1d7564f48a363069b7d77a079"`,
+      `"0xbf944a7a752b2cfab0418d5fb4591c5a7ff62976488edce11794d7f35fb34f41"`,
     )
   })
 
-  test('behavior: `genesisConfig` and `{ account }` produce identical digests', () => {
+  test('behavior: `initialConfig` and `{ account }` produce identical digests', () => {
     const account = MultisigConfig.getAddress(singleOwnerConfig)
     const payload = `0x${'42'.repeat(32)}` as const
     expect(
       MultisigConfig.getSignPayload({
         payload,
-        genesisConfig: singleOwnerConfig,
+        initialConfig: singleOwnerConfig,
       }),
     ).toBe(MultisigConfig.getSignPayload({ payload, account }))
   })
+
+  test('differs for a different config version', () => {
+    const value = {
+      payload: `0x${'42'.repeat(32)}` as const,
+      initialConfig: singleOwnerConfig,
+    }
+    expect(MultisigConfig.getSignPayload(value)).not.toBe(
+      MultisigConfig.getSignPayload({ ...value, version: 1n }),
+    )
+  })
+
+  test('defaults the config version to zero', () => {
+    const value = {
+      payload: `0x${'42'.repeat(32)}` as const,
+      initialConfig: singleOwnerConfig,
+    }
+    expect(MultisigConfig.getSignPayload(value)).toBe(
+      MultisigConfig.getSignPayload({ ...value, version: 0n }),
+    )
+  })
 })
 
 describe('toTuple / fromTuple', () => {
@@ -149,8 +169,8 @@ describe('assert / validate', () => {
     expect(MultisigConfig.validate({ threshold: 1, owners: [] })).toBe(false)
   })
 
-  test('accepts 255 owners', () => {
-    const owners = Array.from({ length: 255 }, (_, i) => ({
+  test('accepts 50 owners', () => {
+    const owners = Array.from({ length: 50 }, (_, i) => ({
       owner: `0x${(i + 1).toString(16).padStart(40, '0')}` as `0x${string}`,
       weight: 1,
     }))
@@ -163,7 +183,7 @@ describe('assert / validate', () => {
   })
 
   test('too many owners', () => {
-    const owners = Array.from({ length: 256 }, (_, i) => ({
+    const owners = Array.from({ length: 51 }, (_, i) => ({
       owner: `0x${(i + 1).toString(16).padStart(40, '0')}` as `0x${string}`,
       weight: 1,
     }))

package/src/tempo/MultisigConfig.ts

@@ -6,7 +6,7 @@ import * as Hex from '../core/Hex.js'
 import type { Compute, OneOf } from '../core/internal/types.js'
 
 /** Maximum number of owners allowed in a native multisig config. */
-export const maxOwners = 255
+export const maxOwners = 50
 
 /** Maximum threshold accepted by a native multisig config. */
 export const maxThreshold = 8
@@ -20,7 +20,7 @@ export const maxSignatures = maxThreshold
  */
 export const maxNestingDepth = 2
 
-/** Maximum encoded byte length for one owner approval. */
+/** Maximum encoded byte length for one primitive owner approval. */
 export const maxOwnerSignatureBytes = 2049
 
 /** Tempo signature type byte for native multisig signatures. */
@@ -233,7 +233,7 @@ export function fromTuple(tuple: Tuple): Config {
  * ```ts twoslash
  * import { MultisigConfig } from 'ox/tempo'
  *
- * const genesisConfig = MultisigConfig.from({
+ * const initialConfig = MultisigConfig.from({
  *   threshold: 1,
  *   owners: [
  *     {
@@ -243,7 +243,7 @@ export function fromTuple(tuple: Tuple): Config {
  *   ]
  * })
  *
- * const address = MultisigConfig.getAddress(genesisConfig)
+ * const address = MultisigConfig.getAddress(initialConfig)
  * ```
  *
  * @param config - The initial (bootstrap) multisig config.
@@ -284,13 +284,13 @@ export declare namespace getAddress {
 /**
  * Computes the digest a native multisig owner approves (signs).
  *
- * `keccak256("tempo:multisig:signature" || inner_digest || account)`,
+ * `keccak256("tempo:multisig:signature" || inner_digest || account || uint64be(version))`,
  * where `inner_digest` is the transaction sign payload
  * ({@link ox#TxEnvelopeTempo.(getSignPayload:function)}).
  *
- * The digest is keyed on the permanent `account` derived from the genesis
- * (bootstrap) config — config updates never change it, so the genesis config
- * is the correct input even for post-update transactions.
+ * The digest is keyed on the permanent `account` derived from the initial
+ * (bootstrap) config and the current config `version`. Bootstrap approvals use
+ * version `0n`, which is also the default; each config update increments it.
  *
  * For a nested multisig owner approval, the parent digest becomes the nested
  * approval's `payload`, with the nested multisig `account`.
@@ -299,7 +299,7 @@ export declare namespace getAddress {
  * ```ts twoslash
  * import { MultisigConfig, TxEnvelopeTempo } from 'ox/tempo'
  *
- * const genesisConfig = MultisigConfig.from({
+ * const initialConfig = MultisigConfig.from({
  *   threshold: 1,
  *   owners: [
  *     {
@@ -316,7 +316,7 @@ export declare namespace getAddress {
  *
  * const digest = MultisigConfig.getSignPayload({
  *   payload: TxEnvelopeTempo.getSignPayload(envelope),
- *   genesisConfig
+ *   initialConfig
  * })
  * ```
  *
@@ -329,7 +329,7 @@ export declare namespace getAddress {
  * ```ts twoslash
  * import { MultisigConfig, TxEnvelopeTempo } from 'ox/tempo'
  *
- * const genesisConfig = MultisigConfig.from({
+ * const initialConfig = MultisigConfig.from({
  *   threshold: 1,
  *   owners: [
  *     {
@@ -338,7 +338,7 @@ export declare namespace getAddress {
  *     }
  *   ]
  * })
- * const account = MultisigConfig.getAddress(genesisConfig)
+ * const account = MultisigConfig.getAddress(initialConfig)
  *
  * const envelope = TxEnvelopeTempo.from({
  *   chainId: 1,
@@ -347,7 +347,8 @@ export declare namespace getAddress {
  *
  * const digest = MultisigConfig.getSignPayload({
  *   payload: TxEnvelopeTempo.getSignPayload(envelope),
- *   account
+ *   account,
+ *   version: 1n
  * })
  * ```
  *
@@ -355,13 +356,18 @@ export declare namespace getAddress {
  * @returns The owner approval digest.
  */
 export function getSignPayload(value: getSignPayload.Value): Hex.Hex {
-  const { payload } = value
+  const { payload, version = 0n } = value
   const account =
     'account' in value && value.account
       ? value.account
-      : getAddress((value as { genesisConfig: Config }).genesisConfig)
+      : getAddress((value as { initialConfig: Config }).initialConfig)
   return Hash.keccak256(
-    Hex.concat(Hex.fromString(signatureDomain), Hex.from(payload), account),
+    Hex.concat(
+      Hex.fromString(signatureDomain),
+      Hex.from(payload),
+      account,
+      Hex.fromNumber(version, { size: 8 }),
+    ),
   )
 }
 
@@ -369,6 +375,8 @@ export declare namespace getSignPayload {
   type Value = {
     /** The inner transaction sign payload (`tx.signature_hash()`). */
     payload: Hex.Hex | Bytes.Bytes
+    /** Current multisig config version. Defaults to `0n`. */
+    version?: bigint | undefined
   } & OneOf<
     | {
         /** The native multisig account address. */
@@ -378,10 +386,10 @@ export declare namespace getSignPayload {
         /**
          * The initial multisig config (the bootstrap config that derived the
          * permanent `account`). Used to derive the account automatically.
-         * Config updates never change `account`, so the genesis config is
-         * also the correct input for post-update transactions.
+         * Config updates never change `account`, so the initial config can
+         * continue deriving the account for post-update transactions.
          */
-        genesisConfig: Config
+        initialConfig: Config
       }
   >
 
@@ -390,6 +398,7 @@ export declare namespace getSignPayload {
     | Hash.keccak256.ErrorType
     | Hex.concat.ErrorType
     | Hex.from.ErrorType
+    | Hex.fromNumber.ErrorType
     | Errors.GlobalErrorType
 }
 

package/src/tempo/SignatureEnvelope.test.ts

@@ -1116,7 +1116,7 @@ describe('from', () => {
   })
 
   describe('multisig', () => {
-    const genesisConfig = MultisigConfig.from({
+    const initialConfig = MultisigConfig.from({
       threshold: 1,
       owners: [
         {
@@ -1126,29 +1126,29 @@ describe('from', () => {
       ],
     })
 
-    test('behavior: derives `account` from `genesisConfig`', () => {
+    test('behavior: derives `account` from `initialConfig`', () => {
       const envelope = SignatureEnvelope.from({
-        genesisConfig,
+        initialConfig,
         signatures: [SignatureEnvelope.from(signature_secp256k1)],
       })
 
       expect(envelope).toMatchObject({
         type: 'multisig',
-        account: MultisigConfig.getAddress(genesisConfig),
+        account: MultisigConfig.getAddress(initialConfig),
       })
-      expect('genesisConfig' in envelope).toBe(false)
+      expect('initialConfig' in envelope).toBe(false)
       expect((envelope as SignatureEnvelope.Multisig).init).toBeUndefined()
     })
 
-    test('behavior: `init: true` opts into bootstrap (uses `genesisConfig` as `init`)', () => {
+    test('behavior: `init: true` opts into bootstrap (uses `initialConfig` as `init`)', () => {
       const envelope = SignatureEnvelope.from({
-        genesisConfig,
+        initialConfig,
         signatures: [SignatureEnvelope.from(signature_secp256k1)],
         init: true,
       })
 
       expect((envelope as SignatureEnvelope.Multisig).init).toEqual(
-        genesisConfig,
+        initialConfig,
       )
     })
 
@@ -1163,7 +1163,7 @@ describe('from', () => {
         ],
       })
       const envelope = SignatureEnvelope.from({
-        genesisConfig,
+        initialConfig,
         signatures: [SignatureEnvelope.from(signature_secp256k1)],
         init: otherConfig,
       })
@@ -1172,7 +1172,7 @@ describe('from', () => {
     })
 
     test('behavior: `{ account }` form still works', () => {
-      const account = MultisigConfig.getAddress(genesisConfig)
+      const account = MultisigConfig.getAddress(initialConfig)
       const envelope = SignatureEnvelope.from({
         account,
         signatures: [SignatureEnvelope.from(signature_secp256k1)],
@@ -1793,7 +1793,7 @@ describe('serialize', () => {
 })
 
 describe('sortMultisigApprovals', () => {
-  // Build owner key pairs first so we can construct a real genesis config
+  // Build owner key pairs first so we can construct a real initial config
   // whose owner set matches the keys that produce the approvals below.
   const ownerKeys = Array.from({ length: 3 }, () => {
     const privateKey = Secp256k1.randomPrivateKey()
@@ -1806,12 +1806,15 @@ describe('sortMultisigApprovals', () => {
     Hex.toBigInt(a.address) < Hex.toBigInt(b.address) ? -1 : 1,
   )
 
-  const genesisConfig = MultisigConfig.from({
+  const initialConfig = MultisigConfig.from({
     threshold: 2,
     owners: ascendingOwners.map((o) => ({ owner: o.address, weight: 1 })),
   })
   const payload = `0x${'42'.repeat(32)}` as const
-  const digest = MultisigConfig.getSignPayload({ payload, genesisConfig })
+  const digest = MultisigConfig.getSignPayload({
+    payload,
+    initialConfig,
+  })
 
   const owners = ownerKeys.map((owner) => ({
     address: owner.address,
@@ -1826,7 +1829,7 @@ describe('sortMultisigApprovals', () => {
 
   test('behavior: orders approvals ascending by recovered owner address', () => {
     const ordered = SignatureEnvelope.sortMultisigApprovals({
-      genesisConfig,
+      initialConfig,
       payload,
       // Provide approvals in reverse of the canonical order.
       signatures: [...ascending].reverse().map((owner) => owner.signature),
@@ -1838,7 +1841,7 @@ describe('sortMultisigApprovals', () => {
     const signatures = ascending.map((owner) => owner.signature)
     expect(
       SignatureEnvelope.sortMultisigApprovals({
-        genesisConfig,
+        initialConfig,
         payload,
         signatures,
       }),
@@ -1847,7 +1850,7 @@ describe('sortMultisigApprovals', () => {
 
   test('behavior: recovered order matches the config owner order', () => {
     const ordered = SignatureEnvelope.sortMultisigApprovals({
-      genesisConfig,
+      initialConfig,
       payload,
       signatures: owners.map((owner) => owner.signature),
     })
@@ -1857,12 +1860,12 @@ describe('sortMultisigApprovals', () => {
     expect(recovered).toEqual(ascending.map((owner) => owner.address))
   })
 
-  test('behavior: `genesisConfig` and `{ account }` produce identical ordering', () => {
-    const account = MultisigConfig.getAddress(genesisConfig)
+  test('behavior: `initialConfig` and `{ account }` produce identical ordering', () => {
+    const account = MultisigConfig.getAddress(initialConfig)
     const signatures = owners.map((owner) => owner.signature)
 
     const fromConfig = SignatureEnvelope.sortMultisigApprovals({
-      genesisConfig,
+      initialConfig,
       payload,
       signatures,
     })
@@ -3041,6 +3044,14 @@ describe('multisig', () => {
     ).toThrowErrorMatchingInlineSnapshot(
       `[SignatureEnvelope.InvalidMultisigApprovalError: Invalid native multisig owner approval: multisig owner signature exceeds 2049 bytes.]`,
     )
+
+    const serialized = Hex.concat(
+      '0x05',
+      Rlp.fromHex([account, [SignatureEnvelope.serialize(oversized)]]),
+    )
+    expect(() => SignatureEnvelope.deserialize(serialized)).toThrowError(
+      SignatureEnvelope.InvalidSerializedError,
+    )
   })
 
   test('assert: rejects keychain owner approvals', () => {
@@ -3082,6 +3093,40 @@ describe('multisig', () => {
       expect(() => SignatureEnvelope.assert(depth2)).not.toThrowError()
     })
 
+    test('accepts a nested approval above the primitive byte limit', () => {
+      const primitive = SignatureEnvelope.from({
+        ...signature_webauthn,
+        metadata: {
+          ...signature_webauthn.metadata,
+          clientDataJSON: JSON.stringify({ value: 'x'.repeat(1_050) }),
+        },
+        signature: {
+          r: signature_webauthn.signature.r,
+          s: signature_webauthn.signature.s,
+        },
+      })
+      const largeNested = SignatureEnvelope.from({
+        type: 'multisig',
+        account: nestedAccount,
+        signatures: [primitive, primitive],
+      })
+      expect(Hex.size(SignatureEnvelope.serialize(primitive))).toBeLessThan(
+        MultisigConfig.maxOwnerSignatureBytes,
+      )
+      expect(
+        Hex.size(SignatureEnvelope.serialize(largeNested)),
+      ).toBeGreaterThan(MultisigConfig.maxOwnerSignatureBytes)
+
+      const parent = SignatureEnvelope.from({
+        type: 'multisig',
+        account,
+        signatures: [largeNested],
+      })
+      expect(
+        SignatureEnvelope.deserialize(SignatureEnvelope.serialize(parent)),
+      ).toEqual(parent)
+    })
+
     test('assert: rejects nesting deeper than the maximum', () => {
       const depth3 = SignatureEnvelope.from({
         type: 'multisig',