ox 0.14.55 → 0.14.57

package/tempo/{MultisigConfig.ts → AccountConfig.ts}

@@ -9,39 +9,52 @@ import type { Compute } from '../core/internal/types.js'
 /** Maximum encoded byte length for one primitive owner approval. */
 export const maxOwnerSignatureBytes = 2049
 
-/** Maximum number of owners allowed in a native multisig config. */
+/** Maximum number of owners allowed in an account config. */
 export const maxOwners = 48
 
-/** Maximum number of owner approvals in a native multisig signature. */
+/** Maximum number of owner approvals in a configurable account signature. */
 export const maxSignatures = 8
 
-/** Maximum threshold accepted by a native multisig config. */
-export const maxThreshold = 8
+/**
+ * Maximum threshold accepted by an account config.
+ *
+ * The threshold must also be reachable by at most {@link ox#AccountConfig.maxSignatures}
+ * owner approvals.
+ */
+export const maxThreshold = 0xff
 
-/** Maximum version accepted by a native multisig config. */
+/** Maximum version accepted by an account config. */
 export const maxVersion = 2n ** 64n - 1n
 
-/** Tempo signature type byte for native multisig signatures. */
+/** Tempo signature type byte for configurable account 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 configurable account address derivation. */
+const accountDomain = 'tempo:configurable-account:account'
 
-/** Domain prefix for native multisig configuration commitments. */
-const configDomain = 'tempo:multisig:config'
+/** Domain prefix for account configuration commitments. */
+const configDomain = 'tempo:configurable-account:config'
 
-/** Keccak-256 of the canonical recovery wallet creation code. */
-const recoveryWalletInitCodeHash =
+/**
+ * Keccak-256 of the account proxy creation code.
+ *
+ * Placeholder until [TIP-1110](https://tips.sh/1110) fixes the canonical
+ * account proxy, which will change every derived address.
+ */
+const accountProxyInitCodeHash =
   '0x583cc63a2e37f645b43eac911b1a6d6de08b83abdc308c61364edda8cfc3bd37'
 
-/** Domain prefix for native multisig owner approvals. */
-const signatureDomain = 'tempo:multisig:signature'
+/** Domain prefix for configurable account owner approvals. */
+const signatureDomain = 'tempo:configurable-account:signature'
+
+/** Domain prefix for the salt of an account migrated in place. */
+const upgradeDomain = 'tempo:configurable-account:upgrade'
 
 /**
- * Complete native multisig configuration witness.
+ * Complete account configuration witness.
  */
 export type Config<bigintType = bigint, numberType = number> = Compute<{
   /** Weighted owner list, strictly ascending by owner address. */
@@ -54,7 +67,7 @@ export type Config<bigintType = bigint, numberType = number> = Compute<{
   version: bigintType
 }>
 
-/** Input accepted when constructing a native multisig configuration. */
+/** Input accepted when constructing an account configuration. */
 export type Input<
   versionType extends bigint | number = bigint | number,
   numberType = number,
@@ -63,7 +76,7 @@ export type Input<
   owners: readonly Owner<numberType>[]
   /**
    * Caller-chosen 32-byte salt mixed into the derived account address.
-   * Defaults to the zero salt (`MultisigConfig.zeroSalt`) when omitted.
+   * Defaults to the zero salt (`AccountConfig.zeroSalt`) when omitted.
    */
   salt?: Hex.Hex | undefined
   /** Minimum total owner weight required to authorize a transaction. */
@@ -72,7 +85,7 @@ export type Input<
   version?: versionType | undefined
 }>
 
-/** Native multisig owner entry. */
+/** Account config owner entry. */
 export type Owner<numberType = number> = {
   /** Owner address (recovered from the owner's approval). */
   owner: Address.Address
@@ -80,10 +93,10 @@ export type Owner<numberType = number> = {
   weight: numberType
 }
 
-/** JSON-RPC representation of a native multisig configuration. */
+/** JSON-RPC representation of an account configuration. */
 export type Rpc = Config<Hex.Hex, number>
 
-/** RLP tuple representation of a {@link ox#MultisigConfig.Config}. */
+/** RLP tuple representation of a {@link ox#AccountConfig.Config}. */
 export type Tuple = readonly [
   salt: Hex.Hex,
   version: Hex.Hex,
@@ -92,7 +105,7 @@ export type Tuple = readonly [
 ]
 
 /**
- * Asserts that a native multisig {@link ox#MultisigConfig.Config} is valid.
+ * Asserts that an {@link ox#AccountConfig.Config} is valid.
  *
  * Mirrors the Tempo configuration rules: owners non-empty and
  * `<= maxOwners`, strictly ascending unique nonzero owner addresses, nonzero
@@ -102,9 +115,9 @@ export type Tuple = readonly [
  *
  * @example
  * ```ts twoslash
- * import { MultisigConfig } from 'ox/tempo'
+ * import { AccountConfig } from 'ox/tempo'
  *
- * MultisigConfig.assert({
+ * AccountConfig.assert({
  *   threshold: 1,
  *   owners: [
  *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
@@ -112,7 +125,7 @@ export type Tuple = readonly [
  * })
  * ```
  *
- * @param config - The multisig config.
+ * @param config - The account config.
  */
 export function assert<
   versionType extends bigint | number = bigint | number,
@@ -183,16 +196,16 @@ export declare namespace assert {
 }
 
 /**
- * Normalizes a native multisig {@link ox#MultisigConfig.Config}.
+ * Normalizes an {@link ox#AccountConfig.Config}.
  *
  * Sorts owners into strictly ascending `owner` address order (the canonical
  * form required for account derivation) and asserts the config is valid.
  *
  * @example
  * ```ts twoslash
- * import { MultisigConfig } from 'ox/tempo'
+ * import { AccountConfig } from 'ox/tempo'
  *
- * const config = MultisigConfig.from({
+ * const config = AccountConfig.from({
  *   owners: [
  *     { owner: '0x2222222222222222222222222222222222222222', weight: 1 },
  *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
@@ -202,8 +215,8 @@ export declare namespace assert {
  * // owners are now sorted ascending by address
  * ```
  *
- * @param config - The multisig config.
- * @returns The normalized multisig config.
+ * @param config - The account config.
+ * @returns The normalized account config.
  */
 export function from<numberType = number>(
   config: Input<0 | 0n, numberType> & { version?: 0 | 0n | undefined },
@@ -237,13 +250,13 @@ export function from<numberType = number>(
 }
 
 /**
- * Converts a JSON-RPC multisig configuration to its domain representation.
+ * Converts a JSON-RPC account configuration to its domain representation.
  *
  * @example
  * ```ts twoslash
- * import { MultisigConfig } from 'ox/tempo'
+ * import { AccountConfig } from 'ox/tempo'
  *
- * const config = MultisigConfig.fromRpc({
+ * const config = AccountConfig.fromRpc({
  *   owners: [
  *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
  *   ],
@@ -253,8 +266,8 @@ export function from<numberType = number>(
  * })
  * ```
  *
- * @param config - The JSON-RPC multisig configuration.
- * @returns The normalized multisig configuration.
+ * @param config - The JSON-RPC account configuration.
+ * @returns The normalized account configuration.
  */
 export function fromRpc(config: Rpc): Config {
   return from({
@@ -271,14 +284,14 @@ export declare namespace fromRpc {
 }
 
 /**
- * Converts an RLP {@link ox#MultisigConfig.Tuple} back to a
- * {@link ox#MultisigConfig.Config}.
+ * Converts an RLP {@link ox#AccountConfig.Tuple} back to a
+ * {@link ox#AccountConfig.Config}.
  *
  * @example
  * ```ts twoslash
- * import { MultisigConfig } from 'ox/tempo'
+ * import { AccountConfig } from 'ox/tempo'
  *
- * const config = MultisigConfig.fromTuple([
+ * const config = AccountConfig.fromTuple([
  *   `0x${'00'.repeat(32)}`,
  *   '0x',
  *   '0x01',
@@ -287,7 +300,7 @@ export declare namespace fromRpc {
  * ```
  *
  * @param tuple - The RLP tuple.
- * @returns The multisig config.
+ * @returns The account config.
  */
 export function fromTuple(tuple: Tuple): Config {
   const [salt, version, threshold, owners] = tuple
@@ -331,34 +344,97 @@ export function fromTuple(tuple: Tuple): Config {
 }
 
 /**
- * Derives the stable native multisig account address.
+ * Derives the configuration an existing account installs when it migrates in
+ * place with the `upgradeAccount` precompile call
+ * ([TIP-1113](https://tips.sh/1113)).
+ *
+ * The account keeps its address. Its salt is
+ * `keccak256("tempo:configurable-account:upgrade" || account)` and its version
+ * is `1n`. Owners are sorted into canonical order and the config is validated.
+ * The account itself may be listed as an owner.
+ *
+ * @example
+ * ```ts twoslash
+ * import { AccountConfig } from 'ox/tempo'
+ *
+ * const config = AccountConfig.fromUpgrade(
+ *   '0x3333333333333333333333333333333333333333',
+ *   {
+ *     owners: [
+ *       {
+ *         owner: '0x1111111111111111111111111111111111111111',
+ *         weight: 1
+ *       }
+ *     ],
+ *     threshold: 1
+ *   }
+ * )
+ * // config.version === 1n
+ * ```
+ *
+ * @param account - The account migrating in place.
+ * @param options - The owners and threshold to install.
+ * @returns The installed account config.
+ */
+export function fromUpgrade<numberType = number>(
+  account: Address.Address,
+  options: fromUpgrade.Options<numberType>,
+): Config<1n, numberType> {
+  Address.assert(account)
+  return from({
+    owners: options.owners,
+    salt: Hash.keccak256(Hex.concat(Hex.fromString(upgradeDomain), account)),
+    threshold: options.threshold,
+    version: 1n,
+  })
+}
+
+export declare namespace fromUpgrade {
+  type Options<numberType = number> = {
+    /** Weighted owners to install. Sorted into canonical order. */
+    owners: readonly Owner<numberType>[]
+    /** Minimum total owner weight required for authorization. */
+    threshold: numberType
+  }
+
+  type ErrorType =
+    | Address.assert.ErrorType
+    | assert.ErrorType
+    | Hash.keccak256.ErrorType
+    | Hex.concat.ErrorType
+    | Hex.fromString.ErrorType
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Derives the stable configurable account address.
  *
  * The initial config is hashed into a CREATE2 salt using fixed-width
  * big-endian fields, not RLP. The account uses the chain-configured recovery
- * factory and wallet init-code hash.
+ * factory and account proxy init-code hash.
  *
  * The address is derived once from the initial version-0 config. Config
  * updates do not change it.
  *
  * @example
  * ```ts twoslash
- * import { MultisigConfig } from 'ox/tempo'
+ * import { AccountConfig } from 'ox/tempo'
  *
- * const initialConfig = MultisigConfig.from({
+ * const initialConfig = AccountConfig.from({
  *   owners: [
  *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
  *   ],
  *   threshold: 1,
  * })
  *
- * const address = MultisigConfig.getAddress(initialConfig, {
+ * const address = AccountConfig.getAddress(initialConfig, {
  *   factory: '0x7171717171717171717171717171717171717171'
  * })
  * ```
  *
- * @param config - The initial multisig config.
+ * @param config - The initial account config.
  * @param options - The recovery factory configured by the chain.
- * @returns The multisig account address.
+ * @returns The configurable account address.
  */
 export function getAddress(
   config: Input,
@@ -383,7 +459,7 @@ export function getAddress(
     ),
   )
   const account = ContractAddress.fromCreate2({
-    bytecodeHash: recoveryWalletInitCodeHash,
+    bytecodeHash: accountProxyInitCodeHash,
     from: options.factory,
     salt: accountSalt,
   })
@@ -413,16 +489,16 @@ export declare namespace getAddress {
 }
 
 /**
- * Computes the commitment for a native multisig configuration.
+ * Computes the commitment for an account configuration.
  *
  * The commitment uses raw fixed-width fields, not RLP or ABI encoding:
- * `keccak256("tempo:multisig:config" || salt || uint64be(version) || uint8(threshold) || uint8(owners.length) || owners)`.
+ * `keccak256("tempo:configurable-account:config" || salt || uint64be(version) || uint8(threshold) || uint8(owners.length) || owners)`.
  *
  * @example
  * ```ts twoslash
- * import { MultisigConfig } from 'ox/tempo'
+ * import { AccountConfig } from 'ox/tempo'
  *
- * const commitment = MultisigConfig.getCommitment({
+ * const commitment = AccountConfig.getCommitment({
  *   owners: [
  *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
  *   ],
@@ -431,7 +507,7 @@ export declare namespace getAddress {
  * })
  * ```
  *
- * @param config - The complete multisig configuration.
+ * @param config - The complete account configuration.
  * @returns The configuration commitment.
  */
 export function getCommitment(config: Input): Hex.Hex {
@@ -462,9 +538,9 @@ export declare namespace getCommitment {
 }
 
 /**
- * Computes the digest a native multisig owner approves (signs).
+ * Computes the digest a configurable account owner approves (signs).
  *
- * `keccak256("tempo:multisig:signature" || inner_digest || account || uint64be(version))`,
+ * `keccak256("tempo:configurable-account:signature" || inner_digest || account || uint64be(version))`,
  * where `inner_digest` is the transaction sign payload
  * ({@link ox#TxEnvelopeTempo.(getSignPayload:function)}).
  *
@@ -474,9 +550,9 @@ export declare namespace getCommitment {
  *
  * @example
  * ```ts twoslash
- * import { MultisigConfig, TxEnvelopeTempo } from 'ox/tempo'
+ * import { AccountConfig, TxEnvelopeTempo } from 'ox/tempo'
  *
- * const config = MultisigConfig.from({
+ * const config = AccountConfig.from({
  *   owners: [
  *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
  *   ],
@@ -488,8 +564,8 @@ export declare namespace getCommitment {
  *   calls: [],
  * })
  *
- * const digest = MultisigConfig.getSignPayload({
- *   account: MultisigConfig.getAddress(config, {
+ * const digest = AccountConfig.getSignPayload({
+ *   account: AccountConfig.getAddress(config, {
  *     factory: '0x7171717171717171717171717171717171717171'
  *   }),
  *   config,
@@ -518,7 +594,7 @@ export function getSignPayload(value: getSignPayload.Value): Hex.Hex {
 
 export declare namespace getSignPayload {
   type Value = {
-    /** The native multisig account address. */
+    /** The configurable account address. */
     account: Address.Address
     /** Configuration whose version applies to the approval. */
     config: Pick<Config<bigint | number>, 'version'>
@@ -536,13 +612,13 @@ export declare namespace getSignPayload {
 }
 
 /**
- * Converts a multisig configuration to its JSON-RPC representation.
+ * Converts an account configuration to its JSON-RPC representation.
  *
  * @example
  * ```ts twoslash
- * import { MultisigConfig } from 'ox/tempo'
+ * import { AccountConfig } from 'ox/tempo'
  *
- * const config = MultisigConfig.toRpc({
+ * const config = AccountConfig.toRpc({
  *   owners: [
  *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
  *   ],
@@ -550,8 +626,8 @@ export declare namespace getSignPayload {
  * })
  * ```
  *
- * @param config - The multisig configuration.
- * @returns The JSON-RPC multisig configuration.
+ * @param config - The account configuration.
+ * @returns The JSON-RPC account configuration.
  */
 export function toRpc(config: Input): Rpc {
   const value = from(config)
@@ -574,7 +650,7 @@ export declare namespace toRpc {
 }
 
 /**
- * Converts a {@link ox#MultisigConfig.Config} to its RLP tuple form.
+ * Converts a {@link ox#AccountConfig.Config} to its RLP tuple form.
  *
  * Tuple shape: `[salt, version, threshold, [[owner, weight], ...]]`. The
  * 32-byte `salt` encodes as a full fixed-width string; other integers use
@@ -582,9 +658,9 @@ export declare namespace toRpc {
  *
  * @example
  * ```ts twoslash
- * import { MultisigConfig } from 'ox/tempo'
+ * import { AccountConfig } from 'ox/tempo'
  *
- * const tuple = MultisigConfig.toTuple({
+ * const tuple = AccountConfig.toTuple({
  *   owners: [
  *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
  *   ],
@@ -592,7 +668,7 @@ export declare namespace toRpc {
  * })
  * ```
  *
- * @param config - The multisig config.
+ * @param config - The account config.
  * @returns The RLP tuple.
  */
 export function toTuple(config: Input): Tuple {
@@ -613,14 +689,75 @@ export function toTuple(config: Input): Tuple {
 }
 
 /**
- * Validates a native multisig {@link ox#MultisigConfig.Config}. Returns `true`
+ * Derives the configuration that replaces the current one in an owner update.
+ *
+ * Mirrors the `updateConfig` precompile ([TIP-1109](https://tips.sh/1109)):
+ * keeps the current salt, increments the version by one, and replaces the
+ * owners and threshold. Owners are sorted into canonical order and the next
+ * configuration is validated. The account address does not change.
+ *
+ * @example
+ * ```ts twoslash
+ * import { AccountConfig } from 'ox/tempo'
+ *
+ * const initialConfig = AccountConfig.from({
+ *   owners: [
+ *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
+ *   ],
+ *   threshold: 1,
+ * })
+ *
+ * const config = AccountConfig.update(initialConfig, {
+ *   owners: [
+ *     { owner: '0x2222222222222222222222222222222222222222', weight: 1 },
+ *   ],
+ *   threshold: 1,
+ * })
+ * // config.version === 1n, with the initial salt
+ * ```
+ *
+ * @param config - The current account config.
+ * @param options - The replacement owners and threshold.
+ * @returns The next account config.
+ */
+export function update<numberType = number>(
+  config: Input<bigint | number, numberType>,
+  options: update.Options<numberType>,
+): Config<bigint, numberType> {
+  const current = from(config)
+  if (current.version === maxVersion)
+    throw new InvalidConfigError({ reason: 'version overflow' })
+  return from({
+    owners: options.owners,
+    salt: current.salt,
+    threshold: options.threshold,
+    version: current.version + 1n,
+  })
+}
+
+export declare namespace update {
+  type Options<numberType = number> = {
+    /** Replacement weighted owners. Sorted into canonical order. */
+    owners: readonly Owner<numberType>[]
+    /** Replacement minimum total owner weight required for authorization. */
+    threshold: numberType
+  }
+
+  type ErrorType =
+    | assert.ErrorType
+    | InvalidConfigError
+    | Errors.GlobalErrorType
+}
+
+/**
+ * Validates an {@link ox#AccountConfig.Config}. Returns `true`
  * if valid, `false` otherwise.
  *
  * @example
  * ```ts twoslash
- * import { MultisigConfig } from 'ox/tempo'
+ * import { AccountConfig } from 'ox/tempo'
  *
- * const valid = MultisigConfig.validate({
+ * const valid = AccountConfig.validate({
  *   owners: [
  *     { owner: '0x1111111111111111111111111111111111111111', weight: 1 },
  *   ],
@@ -629,7 +766,7 @@ export function toTuple(config: Input): Tuple {
  * // @log: true
  * ```
  *
- * @param config - The multisig config.
+ * @param config - The account config.
  * @returns Whether the config is valid.
  */
 export function validate(config: Input): boolean {
@@ -641,11 +778,11 @@ export function validate(config: Input): boolean {
   }
 }
 
-/** Thrown when a native multisig config is invalid. */
+/** Thrown when an account config is invalid. */
 export class InvalidConfigError extends Errors.BaseError {
-  override readonly name = 'MultisigConfig.InvalidConfigError'
+  override readonly name = 'AccountConfig.InvalidConfigError'
   constructor({ reason }: { reason: string }) {
-    super(`Invalid native multisig config: ${reason}.`)
+    super(`Invalid account config: ${reason}.`)
   }
 }
 

package/tempo/AccountOperation/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "types": "../../_types/tempo/AccountOperation.d.ts",
+  "main": "../../_cjs/tempo/AccountOperation.js",
+  "module": "../../_esm/tempo/AccountOperation.js"
+}

package/tempo/AccountOperation.test-d/package.json

@@ -0,0 +1,6 @@
+{
+  "type": "module",
+  "types": "../../_types/tempo/AccountOperation.test-d.d.ts",
+  "main": "../../_cjs/tempo/AccountOperation.test-d.js",
+  "module": "../../_esm/tempo/AccountOperation.test-d.js"
+}

package/tempo/AccountOperation.test-d.ts

@@ -0,0 +1,71 @@
+import { expectTypeOf, test } from 'vitest'
+import type * as Hex from '../core/Hex.js'
+import * as AccountOperation from './AccountOperation.js'
+import type * as TxEnvelopeTempo from './TxEnvelopeTempo.js'
+
+declare const transaction: AccountOperation.TransactionOperation
+declare const transactionRpc: AccountOperation.TransactionRpc
+declare const keyAuthorization: AccountOperation.KeyAuthorizationOperation
+declare const keyAuthorizationRpc: AccountOperation.KeyAuthorizationRpc
+declare const operation: AccountOperation.Operation
+declare const operationRpc: AccountOperation.Rpc
+declare const getHashOptions: AccountOperation.getHash.Options
+declare const selectApprovalsOptions: AccountOperation.selectApprovals.Options
+declare const serializeTransactionOptions: AccountOperation.serializeTransaction.Options
+
+test('preserves operation kinds during validation', () => {
+  expectTypeOf(
+    AccountOperation.from(transaction),
+  ).toEqualTypeOf<AccountOperation.TransactionOperation>()
+  expectTypeOf(
+    AccountOperation.from(keyAuthorization),
+  ).toEqualTypeOf<AccountOperation.KeyAuthorizationOperation>()
+  expectTypeOf(
+    AccountOperation.from(operation),
+  ).toEqualTypeOf<AccountOperation.Operation>()
+})
+
+test('preserves operation kinds during RPC conversion', () => {
+  expectTypeOf(
+    AccountOperation.fromRpc(transactionRpc),
+  ).toEqualTypeOf<AccountOperation.TransactionOperation>()
+  expectTypeOf(
+    AccountOperation.fromRpc(keyAuthorizationRpc),
+  ).toEqualTypeOf<AccountOperation.KeyAuthorizationOperation>()
+  expectTypeOf(
+    AccountOperation.toRpc(transaction),
+  ).toEqualTypeOf<AccountOperation.TransactionRpc>()
+  expectTypeOf(
+    AccountOperation.toRpc(keyAuthorization),
+  ).toEqualTypeOf<AccountOperation.KeyAuthorizationRpc>()
+  expectTypeOf(
+    AccountOperation.fromRpc(operationRpc),
+  ).toEqualTypeOf<AccountOperation.Operation>()
+  expectTypeOf(
+    AccountOperation.toRpc(operation),
+  ).toEqualTypeOf<AccountOperation.Rpc>()
+})
+
+test('uses JSON-RPC quantities only in RPC operations', () => {
+  expectTypeOf<
+    AccountOperation.Operation['config']['version']
+  >().toEqualTypeOf<bigint>()
+  expectTypeOf<
+    AccountOperation.Rpc['config']['version']
+  >().toEqualTypeOf<Hex.Hex>()
+})
+
+test('operation helpers return narrow types', async () => {
+  expectTypeOf(
+    AccountOperation.getHash(getHashOptions),
+  ).toEqualTypeOf<Hex.Hex>()
+  expectTypeOf(
+    await AccountOperation.selectApprovals(selectApprovalsOptions),
+  ).toEqualTypeOf<AccountOperation.selectApprovals.ReturnValue>()
+  expectTypeOf(
+    AccountOperation.serializeTransaction(
+      transaction,
+      serializeTransactionOptions,
+    ),
+  ).toEqualTypeOf<TxEnvelopeTempo.Serialized>()
+})