ox 1.6.1 → 1.6.3

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',

package/src/tempo/SignatureEnvelope.ts

@@ -434,12 +434,13 @@ function assertMultisig(envelope: Multisig, depth: number): void {
           reason: 'nested multisig owner approvals cannot carry `init`',
         })
       assertMultisig(multisig, depth + 1)
-    } else assert(inner)
-
-    if (Hex.size(serialize(inner)) > MultisigConfig.maxOwnerSignatureBytes)
-      throw new InvalidMultisigApprovalError({
-        reason: `multisig owner signature exceeds ${MultisigConfig.maxOwnerSignatureBytes} bytes`,
-      })
+    } else {
+      assert(inner)
+      if (Hex.size(serialize(inner)) > MultisigConfig.maxOwnerSignatureBytes)
+        throw new InvalidMultisigApprovalError({
+          reason: `multisig owner signature exceeds ${MultisigConfig.maxOwnerSignatureBytes} bytes`,
+        })
+    }
   }
 }
 
@@ -750,7 +751,10 @@ function deserialize_(
       })
     for (const signature of signatures)
       if (
-        Hex.size(signature as Hex.Hex) > MultisigConfig.maxOwnerSignatureBytes
+        Hex.size(signature as Hex.Hex) >
+          MultisigConfig.maxOwnerSignatureBytes &&
+        Hex.slice(signature as Hex.Hex, 0, 1) !==
+          MultisigConfig.signatureTypeByte
       )
         throw new InvalidSerializedError({
           reason: `multisig owner signature exceeds ${MultisigConfig.maxOwnerSignatureBytes} bytes`,
@@ -935,17 +939,17 @@ function deserialize_(
  * ```
  *
  * @example
- * ### Multisig (from genesis config)
+ * ### Multisig (from initial config)
  *
- * Pass `genesisConfig` to derive `account` automatically. Set `init: true` to
- * opt into bootstrap (uses `genesisConfig` as the bootstrap `init`); omit
+ * Pass `initialConfig` to derive `account` automatically. Set `init: true` to
+ * opt into bootstrap (uses `initialConfig` as the bootstrap `init`); omit
  * `init` for subsequent (non-bootstrap) transactions.
  *
  * ```ts twoslash
  * import { Secp256k1 } from 'ox'
  * import { MultisigConfig, SignatureEnvelope } from 'ox/tempo'
  *
- * const genesisConfig = MultisigConfig.from({
+ * const initialConfig = MultisigConfig.from({
  *   threshold: 1,
  *   owners: [
  *     {
@@ -962,14 +966,14 @@ function deserialize_(
  *
  * // Bootstrap transaction
  * const bootstrap = SignatureEnvelope.from({
- *   genesisConfig,
+ *   initialConfig,
  *   signatures: [signature],
  *   init: true
  * })
  *
  * // Subsequent (non-bootstrap) transactions
  * const subsequent = SignatureEnvelope.from({
- *   genesisConfig,
+ *   initialConfig,
  *   signatures: [signature]
  * })
  * ```
@@ -996,20 +1000,20 @@ export function from<const value extends from.Value>(
 
   if (type === 'multisig') {
     const multisig = value as Multisig & {
-      genesisConfig?: MultisigConfig.Config | undefined
+      initialConfig?: MultisigConfig.Config | undefined
       init?: MultisigConfig.Config | boolean | undefined
     }
-    const { genesisConfig, init, ...rest } = multisig
-    // Derive `account` from `genesisConfig` when not provided explicitly.
+    const { initialConfig, init, ...rest } = multisig
+    // Derive `account` from `initialConfig` when not provided explicitly.
     const account = (() => {
       if (rest.account) return rest.account
-      if (genesisConfig) return MultisigConfig.getAddress(genesisConfig)
+      if (initialConfig) return MultisigConfig.getAddress(initialConfig)
       return rest.account
     })()
-    // `init: true` opts into bootstrap using the supplied `genesisConfig`.
+    // `init: true` opts into bootstrap using the supplied `initialConfig`.
     // Otherwise, `init` is treated as the explicit bootstrap config (or
     // omitted).
-    const initSource = init === true ? genesisConfig : init || undefined
+    const initSource = init === true ? initialConfig : init || undefined
     return {
       ...rest,
       account,
@@ -1065,13 +1069,13 @@ export declare namespace from {
 
   /**
    * Multisig envelope input variant where `account` is derived from the
-   * supplied `genesisConfig`. Pass `init: true` to opt into bootstrap (uses
-   * `genesisConfig` as the bootstrap `init`); omit `init` for subsequent
+   * supplied `initialConfig`. Pass `init: true` to opt into bootstrap (uses
+   * `initialConfig` as the bootstrap `init`); omit `init` for subsequent
    * (non-bootstrap) transactions.
    */
-  type MultisigFromGenesisConfig = {
+  type MultisigFromInitialConfig = {
     type?: 'multisig' | undefined
-    genesisConfig: MultisigConfig.Config
+    initialConfig: MultisigConfig.Config
     signatures: readonly SignatureEnvelope[]
     init?: MultisigConfig.Config | boolean | undefined
   }
@@ -1080,7 +1084,7 @@ export declare namespace from {
     | UnionPartialBy<SignatureEnvelope, 'prehash' | 'type'>
     | Secp256k1Flat
     | Serialized
-    | MultisigFromGenesisConfig
+    | MultisigFromInitialConfig
 
   type ReturnValue<value extends Value> = Compute<
     OneOf<
@@ -1088,7 +1092,7 @@ export declare namespace from {
         ? SignatureEnvelope
         : value extends Secp256k1Flat
           ? Secp256k1
-          : value extends MultisigFromGenesisConfig
+          : value extends MultisigFromInitialConfig
             ? Multisig
             : IsNarrowable<value, SignatureEnvelope> extends true
               ? SignatureEnvelope
@@ -1315,7 +1319,7 @@ export function getType<
   // Detect Multisig signature
   if (
     ('account' in envelope ||
-      'genesisConfig' in envelope ||
+      'initialConfig' in envelope ||
       'init' in envelope) &&
     'signatures' in envelope
   )
@@ -1470,7 +1474,7 @@ export declare namespace serialize {
  * recovered owner address. Works for any owner key type (secp256k1, p256,
  * webAuthn).
  *
- * Config updates never change `account`, so the genesis config is the correct
+ * Config updates never change `account`, so the initial config is the correct
  * input even for post-update transactions.
  *
  * @example
@@ -1482,7 +1486,7 @@ export declare namespace serialize {
  *   TxEnvelopeTempo
  * } from 'ox/tempo'
  *
- * const genesisConfig = MultisigConfig.from({
+ * const initialConfig = MultisigConfig.from({
  *   threshold: 2,
  *   owners: [
  *     {
@@ -1505,7 +1509,7 @@ export declare namespace serialize {
  * ]
  * const digest = MultisigConfig.getSignPayload({
  *   payload,
- *   genesisConfig
+ *   initialConfig
  * })
  * const signatures = privateKeys.map((privateKey) =>
  *   SignatureEnvelope.from(
@@ -1515,7 +1519,7 @@ export declare namespace serialize {
  *
  * const ordered = SignatureEnvelope.sortMultisigApprovals({
  *   // [!code focus]
- *   genesisConfig, // [!code focus]
+ *   initialConfig, // [!code focus]
  *   payload, // [!code focus]
  *   signatures // [!code focus]
  * }) // [!code focus]
@@ -1527,11 +1531,15 @@ export declare namespace serialize {
 export function sortMultisigApprovals(
   value: sortMultisigApprovals.Value,
 ): readonly SignatureEnvelope[] {
-  const { payload, signatures } = value
+  const { payload, signatures, version = 0n } = value
   const digest = MultisigConfig.getSignPayload(
-    'genesisConfig' in value && value.genesisConfig
-      ? { payload, genesisConfig: value.genesisConfig }
-      : { payload, account: (value as { account: Address.Address }).account },
+    'initialConfig' in value && value.initialConfig
+      ? { payload, initialConfig: value.initialConfig, version }
+      : {
+          payload,
+          account: (value as { account: Address.Address }).account,
+          version,
+        },
   )
   // Recover each signer once (decorate–sort–undecorate) rather than inside the
   // comparator.
@@ -1550,6 +1558,8 @@ export declare namespace sortMultisigApprovals {
     payload: Hex.Hex | Bytes.Bytes
     /** The owner approvals to order. */
     signatures: readonly SignatureEnvelope[]
+    /** Current multisig config version. Defaults to `0n`. */
+    version?: bigint | undefined
   } & OneOf<
     | {
         /** The native multisig account address. */
@@ -1560,7 +1570,7 @@ export declare namespace sortMultisigApprovals {
          * The initial multisig config (the bootstrap config that derived the
          * permanent `account`). Used to derive the account automatically.
          */
-        genesisConfig: MultisigConfig.Config
+        initialConfig: MultisigConfig.Config
       }
   >
 

package/src/tempo/WithdrawalSenderTag.test-d.ts

@@ -5,6 +5,7 @@ import { expectTypeOf, test } from 'vp/test'
 test('from', () => {
   expectTypeOf(
     WithdrawalSenderTag.from({
+      fallbackNonce: 19n,
       sender: '0x1234567890abcdef1234567890abcdef12345678',
       transactionHash:
         '0xabababababababababababababababababababababababababababababababab',

package/src/tempo/WithdrawalSenderTag.test.ts

@@ -1,22 +1,26 @@
 import { WithdrawalSenderTag } from 'ox/tempo'
 import { expect, test } from 'vp/test'
 
-test('from', () => {
+test('from: production withdrawal', () => {
   const senderTag = WithdrawalSenderTag.from({
-    sender: '0x1234567890abcdef1234567890abcdef12345678',
+    fallbackNonce: 19n,
+    sender: '0x0F0896dbf0465E5c07963301dcFEA1101Fa91EaC',
     transactionHash:
-      '0xabababababababababababababababababababababababababababababababab',
+      '0xae628bdc4bd24a9f9a917825a208baa16c384ab8a96a40cd5146bd20d9b3f6d9',
   })
   expect(senderTag).toMatchInlineSnapshot(
-    `"0x3362fade7333b56b9f3582089ec5915b8a6f6ac13e73a7f90c169e3eb81d8a5e"`,
+    `"0xf1acbae45cd689281144042331e3379cf631a8d2db83057ccf38754a0b0108f2"`,
   )
 })
 
-test('deterministic', () => {
-  const value = {
-    sender: '0x1234567890abcdef1234567890abcdef12345678',
+test('from: internal deposit bounce-back', () => {
+  const senderTag = WithdrawalSenderTag.from({
+    fallbackNonce: 0n,
+    sender: '0x0000000000000000000000000000000000000000',
     transactionHash:
       '0xabababababababababababababababababababababababababababababababab',
-  } as const
-  expect(WithdrawalSenderTag.from(value)).toBe(WithdrawalSenderTag.from(value))
+  })
+  expect(senderTag).toMatchInlineSnapshot(
+    `"0xa86d54e9aab41ae5e520ff0062ff1b4cbd0b2192bb01080a058bb170d84e6457"`,
+  )
 })

package/src/tempo/WithdrawalSenderTag.ts

@@ -8,8 +8,11 @@ import * as Hex from '../core/Hex.js'
  * `WithdrawalProcessed` event for a Zone withdrawal.
  *
  * The `transactionHash` is the Zone transaction containing the
- * `ZoneOutbox.requestWithdrawal` call. The protocol defines the sender tag as
- * `keccak256(abi.encodePacked(sender, transactionHash))`.
+ * `ZoneOutbox.requestWithdrawal` call. The protocol defines a user withdrawal
+ * sender tag as
+ * `keccak256(abi.encodePacked(sender, transactionHash, fallbackNonce))`.
+ * Internal deposit bounce-backs use the canonical zero-sender tag derived from
+ * `address(0)` and `bytes32(0)` without a fallback nonce.
  *
  * [Authenticated Withdrawals Specification](https://github.com/tempoxyz/zones/blob/main/specs/spec.md#authenticated-withdrawals)
  *
@@ -18,27 +21,43 @@ import * as Hex from '../core/Hex.js'
  * import { WithdrawalSenderTag } from 'ox/tempo'
  *
  * const senderTag = WithdrawalSenderTag.from({
+ *   fallbackNonce: 19n,
  *   sender: '0x1234567890abcdef1234567890abcdef12345678',
  *   transactionHash:
  *     '0xabababababababababababababababababababababababababababababababab'
  * })
  * ```
  *
- * @param value - Withdrawal sender and Zone transaction hash.
+ * @param value - Withdrawal sender, Zone transaction hash, and fallback nonce.
  * @returns The sender tag.
  */
 export function from(value: from.Value): Hex.Hex {
-  const { sender, transactionHash } = value
+  const { fallbackNonce, sender, transactionHash } = value
+  if (
+    sender === '0x0000000000000000000000000000000000000000' &&
+    fallbackNonce === 0n
+  )
+    return Hash.keccak256(
+      AbiParameters.encodePacked(
+        ['address', 'bytes32'],
+        [
+          sender,
+          '0x0000000000000000000000000000000000000000000000000000000000000000',
+        ],
+      ),
+    )
   return Hash.keccak256(
     AbiParameters.encodePacked(
-      ['address', 'bytes32'],
-      [sender, transactionHash],
+      ['address', 'bytes32', 'uint64'],
+      [sender, transactionHash, fallbackNonce],
     ),
   )
 }
 
 export declare namespace from {
   export type Value = {
+    /** Public nonce assigned to the withdrawal's private fallback recipient. */
+    fallbackNonce: bigint
     /** Address that requested the withdrawal. */
     sender: Address.Address
     /** Hash of the Zone transaction containing `ZoneOutbox.requestWithdrawal`. */

package/src/tempo/index.ts

@@ -153,7 +153,7 @@ export * as KeyAuthorization from './KeyAuthorization.js'
  * ```ts twoslash
  * import { MultisigConfig } from 'ox/tempo'
  *
- * const genesisConfig = MultisigConfig.from({
+ * const initialConfig = MultisigConfig.from({
  *   threshold: 2,
  *   owners: [
  *     {
@@ -167,7 +167,7 @@ export * as KeyAuthorization from './KeyAuthorization.js'
  *   ]
  * })
  *
- * const account = MultisigConfig.getAddress(genesisConfig)
+ * const account = MultisigConfig.getAddress(initialConfig)
  * ```
  *
  * @category Reference
@@ -533,8 +533,8 @@ export * as VirtualMaster from './VirtualMaster.js'
  * Utilities for deriving the sender tag that correlates a Zone withdrawal with
  * its indexed parent-chain `WithdrawalProcessed` event.
  *
- * The sender tag commits to the withdrawal sender and the Zone transaction hash
- * containing the `ZoneOutbox.requestWithdrawal` call.
+ * The sender tag commits to the withdrawal sender, the Zone transaction hash
+ * containing the `ZoneOutbox.requestWithdrawal` call, and the fallback nonce.
  *
  * [Authenticated Withdrawals Specification](https://github.com/tempoxyz/zones/blob/main/specs/spec.md#authenticated-withdrawals)
  *
@@ -543,6 +543,7 @@ export * as VirtualMaster from './VirtualMaster.js'
  * import { WithdrawalSenderTag } from 'ox/tempo'
  *
  * const senderTag = WithdrawalSenderTag.from({
+ *   fallbackNonce: 19n,
  *   sender: '0x1234567890abcdef1234567890abcdef12345678',
  *   transactionHash:
  *     '0xabababababababababababababababababababababababababababababababab'