ox 0.14.6 → 0.14.8

package/erc8021/Attribution.ts

@@ -1,4 +1,5 @@
 import type * as Address from '../core/Address.js'
+import * as Cbor from '../core/Cbor.js'
 import type * as Errors from '../core/Errors.js'
 import * as Hex from '../core/Hex.js'
 import type { OneOf } from '../core/internal/types.js'
@@ -9,7 +10,9 @@ import type { OneOf } from '../core/internal/types.js'
  * Represents attribution metadata that can be appended to transaction calldata
  * to track entities involved in facilitating a transaction.
  */
-export type Attribution = OneOf<AttributionSchemaId0 | AttributionSchemaId1>
+export type Attribution = OneOf<
+  AttributionSchemaId0 | AttributionSchemaId1 | AttributionSchemaId2
+>
 
 /**
  * Schema 0: Canonical Registry Attribution.
@@ -44,14 +47,50 @@ export type AttributionSchemaId1Registry = {
   chainId: number
 }
 
+/**
+ * Schema 2: CBOR-Encoded Attribution.
+ *
+ * Uses CBOR encoding for extensible transaction annotation with optional fields,
+ * support for arbitrary metadata, and coexistence with other suffix-based systems.
+ */
+export type AttributionSchemaId2 = {
+  /** Application attribution code. */
+  appCode?: string | undefined
+  /** Wallet attribution code. */
+  walletCode?: string | undefined
+  /** Custom code registries keyed by entity type. */
+  registries?: AttributionSchemaId2Registries | undefined
+  /** Arbitrary metadata key-value pairs. */
+  metadata?: Record<string, unknown> | undefined
+  /** Schema identifier (2 for CBOR-encoded). */
+  id?: 2 | undefined
+}
+
+export type AttributionSchemaId2Registries = {
+  /** Custom registry for the application entity. */
+  app?: AttributionSchemaId2Registry | undefined
+  /** Custom registry for the wallet entity. */
+  wallet?: AttributionSchemaId2Registry | undefined
+}
+
+export type AttributionSchemaId2Registry = {
+  /** Address of the custom code registry contract. */
+  address: Address.Address
+  /** Chain ID of the chain the custom code registry contract is deployed on. */
+  chainId: number
+}
+
 /**
  * Attribution schema identifier.
  *
  * - `0`: Canonical registry
  * - `1`: Custom registry
+ * - `2`: CBOR-encoded
  */
 export type SchemaId = NonNullable<
-  AttributionSchemaId0['id'] | AttributionSchemaId1['id']
+  | AttributionSchemaId0['id']
+  | AttributionSchemaId1['id']
+  | AttributionSchemaId2['id']
 >
 
 /**
@@ -84,12 +123,18 @@ export const ercSuffixSize = /*#__PURE__*/ Hex.size(ercSuffix)
  *   }
  * })
  * // @log: 1
+ *
+ * const schemaId3 = Attribution.getSchemaId({
+ *   appCode: 'baseapp',
+ * })
+ * // @log: 2
  * ```
  *
  * @param attribution - The attribution object.
- * @returns The schema ID (0 for canonical registry, 1 for custom registry).
+ * @returns The schema ID (0 for canonical registry, 1 for custom registry, 2 for CBOR-encoded).
  */
 export function getSchemaId(attribution: Attribution): SchemaId {
+  if ('appCode' in attribution || 'walletCode' in attribution) return 2
   if ('codeRegistry' in attribution) return 1
   return 0
 }
@@ -128,12 +173,34 @@ export declare namespace getSchemaId {
  * })
  * ```
  *
+ * @example
+ * ### Schema 2 (CBOR-Encoded)
+ *
+ * ```ts twoslash
+ * import { Attribution } from 'ox/erc8021'
+ *
+ * const suffix = Attribution.toDataSuffix({
+ *   appCode: 'baseapp',
+ *   walletCode: 'privy',
+ *   metadata: { source: 'webapp' },
+ * })
+ * ```
+ *
  * @param attribution - The attribution to convert.
  * @returns The data suffix as a {@link ox#Hex.Hex} value.
  */
 export function toDataSuffix(attribution: Attribution): Hex.Hex {
+  // Determine schema ID
+  const schemaId = getSchemaId(attribution)
+
+  // Schema 2: CBOR-encoded
+  if (schemaId === 2) {
+    const schema2 = attribution as AttributionSchemaId2
+    return schema2ToDataSuffix(schema2)
+  }
+
   // Encode the codes as ASCII strings separated by commas
-  const codesHex = Hex.fromString(attribution.codes.join(','))
+  const codesHex = Hex.fromString((attribution.codes ?? []).join(','))
 
   // Get the byte length of the encoded codes
   const codesLength = Hex.size(codesHex)
@@ -141,14 +208,11 @@ export function toDataSuffix(attribution: Attribution): Hex.Hex {
   // Encode the codes length as 1 byte
   const codesLengthHex = Hex.fromNumber(codesLength, { size: 1 })
 
-  // Determine schema ID
-  const schemaId = getSchemaId(attribution)
   const schemaIdHex = Hex.fromNumber(schemaId, { size: 1 })
 
-  // Build the suffix based on schema
+  // Schema 1: codeRegistryAddress (20 bytes) ∥ chainId ∥ chainIdLength (1 byte) ∥ codes ∥ codesLength (1 byte) ∥ schemaId (1 byte) ∥ ercSuffix
   if (schemaId === 1) {
     const schema1 = attribution as AttributionSchemaId1
-    // Schema 1: codeRegistryAddress (20 bytes) ∥ chainId ∥ chainIdLength (1 byte) ∥ codes ∥ codesLength (1 byte) ∥ schemaId (1 byte) ∥ ercSuffix
     return Hex.concat(
       registryToData(schema1.codeRegistry),
       codesHex,
@@ -169,6 +233,7 @@ export declare namespace toDataSuffix {
     | Hex.fromString.ErrorType
     | Hex.fromNumber.ErrorType
     | Hex.size.ErrorType
+    | Cbor.encode.ErrorType
     | Errors.GlobalErrorType
 }
 
@@ -198,14 +263,26 @@ export declare namespace toDataSuffix {
  * )
  * // @log: {
  * // @log:   codes: ['baseapp', 'morpho'],
- * // @log:   registry: {
- * // @log:       address: '0xcccccccccccccccccccccccccccccccccccccccc`
+ * // @log:   codeRegistry: {
+ * // @log:       address: '0xcccccccccccccccccccccccccccccccccccccccc',
  * // @log:       chainId: 8453,
- * // @log:   }
+ * // @log:   },
  * // @log:   id: 1
  * // @log: }
  * ```
  *
+ * @example
+ * ### Schema 2 (CBOR-Encoded)
+ *
+ * ```ts twoslash
+ * import { Attribution } from 'ox/erc8021'
+ *
+ * const attribution = Attribution.fromData(
+ *   '0xdddddddda161616762617365617070000b0280218021802180218021802180218021'
+ * )
+ * // @log: { appCode: 'baseapp', id: 2 }
+ * ```
+ *
  * @param data - The transaction calldata containing the attribution suffix.
  * @returns The extracted attribution, or undefined if no valid attribution is found.
  */
@@ -270,6 +347,10 @@ export function fromData(data: Hex.Hex): Attribution | undefined {
       id: 1,
     }
   }
+  // Schema 2: CBOR-encoded
+  if (schemaId === 2) {
+    return schema2FromData(data)
+  }
 
   // Unknown schema ID
   return undefined
@@ -325,5 +406,103 @@ export declare namespace fromData {
     | Hex.toNumber.ErrorType
     | Hex.toString.ErrorType
     | Hex.size.ErrorType
+    | Cbor.decode.ErrorType
     | Errors.GlobalErrorType
 }
+
+// ---- Schema 2 helpers ----
+
+/** Internal CBOR map shape matching the ERC-8021 spec. */
+type Schema2CborMap = {
+  a?: string
+  w?: string
+  r?: {
+    a?: { c: string; a: string }
+    w?: { c: string; a: string }
+  }
+  m?: Record<string, unknown>
+}
+
+function schema2ToDataSuffix(attribution: AttributionSchemaId2): Hex.Hex {
+  // Build the CBOR map using single-letter keys per the spec
+  const cborMap: Schema2CborMap = {}
+
+  if (attribution.appCode) cborMap.a = attribution.appCode
+  if (attribution.walletCode) cborMap.w = attribution.walletCode
+
+  if (attribution.registries) {
+    const r: Schema2CborMap['r'] = {}
+    if (attribution.registries.app) {
+      r.a = {
+        c: Hex.fromNumber(attribution.registries.app.chainId),
+        a: attribution.registries.app.address,
+      }
+    }
+    if (attribution.registries.wallet) {
+      r.w = {
+        c: Hex.fromNumber(attribution.registries.wallet.chainId),
+        a: attribution.registries.wallet.address,
+      }
+    }
+    if (r.a || r.w) cborMap.r = r
+  }
+
+  if (attribution.metadata && Object.keys(attribution.metadata).length > 0)
+    cborMap.m = attribution.metadata
+
+  // Encode to CBOR
+  const cborHex = Cbor.encode(cborMap)
+  const cborBytes = Hex.size(cborHex)
+
+  // cborData ∥ cborLength (2 bytes) ∥ schemaId (1 byte) ∥ ercSuffix
+  return Hex.concat(
+    cborHex,
+    Hex.fromNumber(cborBytes, { size: 2 }),
+    Hex.fromNumber(2, { size: 1 }),
+    ercSuffix,
+  )
+}
+
+function schema2FromData(data: Hex.Hex): AttributionSchemaId2 | undefined {
+  // cborLength is 2 bytes before schema ID
+  const cborLengthHex = Hex.slice(
+    data,
+    -ercSuffixSize - 1 - 2,
+    -ercSuffixSize - 1,
+  )
+  const cborLength = Hex.toNumber(cborLengthHex)
+
+  // Extract CBOR data
+  const cborStart = -ercSuffixSize - 1 - 2 - cborLength
+  const cborEnd = -ercSuffixSize - 1 - 2
+  const cborHex = Hex.slice(data, cborStart, cborEnd)
+
+  // Decode CBOR
+  const decoded = Cbor.decode<Schema2CborMap>(cborHex)
+
+  const result: AttributionSchemaId2 = { id: 2 }
+
+  if (typeof decoded.a === 'string') result.appCode = decoded.a
+  if (typeof decoded.w === 'string') result.walletCode = decoded.w
+
+  if (decoded.r) {
+    const registries: AttributionSchemaId2Registries = {}
+    if (decoded.r.a?.c && decoded.r.a?.a) {
+      registries.app = {
+        address: decoded.r.a.a as Address.Address,
+        chainId: Hex.toNumber(decoded.r.a.c as Hex.Hex),
+      }
+    }
+    if (decoded.r.w?.c && decoded.r.w?.a) {
+      registries.wallet = {
+        address: decoded.r.w.a as Address.Address,
+        chainId: Hex.toNumber(decoded.r.w.c as Hex.Hex),
+      }
+    }
+    if (registries.app || registries.wallet) result.registries = registries
+  }
+
+  if (decoded.m && typeof decoded.m === 'object') result.metadata = decoded.m
+
+  return result
+}

package/erc8021/index.ts

@@ -19,6 +19,11 @@ export type {}
  *   codes: ['baseapp', 'morpho'],
  *   codeRegistry: { address: '0x0000000000000000000000000000000000000000', chainId: 1 },
  * })
+ *
+ * const dataSuffix3 = Attribution.toDataSuffix({
+ *   appCode: 'baseapp',
+ *   walletCode: 'privy',
+ * })
  * ```
  *
  * @example

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ox",
   "description": "Ethereum Standard Library",
-  "version": "0.14.6",
+  "version": "0.14.8",
   "main": "./_cjs/index.js",
   "module": "./_esm/index.js",
   "types": "./_types/index.d.ts",

package/tempo/AuthorizationTempo.test.ts

@@ -15,8 +15,8 @@ describe('from', () => {
         chainId: 1,
         nonce: 40n,
       })
-      expectTypeOf(authorization).toEqualTypeOf<{
-        readonly address: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c'
+      expectTypeOf(authorization).toExtend<{
+        address: `0x${string}`
         readonly chainId: 1
         readonly nonce: 40n
       }>()
@@ -48,8 +48,8 @@ describe('from', () => {
           type: 'secp256k1' as const,
         },
       })
-      expectTypeOf(authorization).toEqualTypeOf<{
-        readonly address: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c'
+      expectTypeOf(authorization).toExtend<{
+        address: `0x${string}`
         readonly chainId: 1
         readonly nonce: 40n
         readonly signature: {
@@ -111,7 +111,7 @@ describe('from', () => {
       signature,
     })
     expectTypeOf(authorization_signed).toExtend<{
-      readonly address: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c'
+      readonly address: `0x${string}`
       readonly chainId: 1
       readonly nonce: 40n
     }>()
@@ -152,7 +152,7 @@ describe('from', () => {
       signature: signatureEnvelope,
     })
     expectTypeOf(authorization_signed).toExtend<{
-      readonly address: '0xbe95c3f554e9fc85ec51be69a3d807a0d55bcf2c'
+      readonly address: `0x${string}`
       readonly chainId: 1
       readonly nonce: 40n
     }>()

package/tempo/AuthorizationTempo.ts

@@ -18,10 +18,11 @@ export type AuthorizationTempo<
   signed extends boolean = boolean,
   bigintType = bigint,
   numberType = number,
+  addressType = TempoAddress.Address,
 > = Compute<
   {
     /** Address of the contract to set as code for the Authority. */
-    address: TempoAddress.Address
+    address: addressType
     /** Chain ID to authorize. */
     chainId: numberType
     /** Nonce of the Authority to authorize. */
@@ -283,10 +284,12 @@ export declare namespace from {
   > = Compute<
     authorization extends Rpc
       ? Signed
-      : authorization &
-          (signature extends SignatureEnvelope.from.Value
-            ? { signature: SignatureEnvelope.from.ReturnValue<signature> }
-            : {})
+      : TempoAddress.ResolveAddresses<
+          authorization &
+            (signature extends SignatureEnvelope.from.Value
+              ? { signature: SignatureEnvelope.from.ReturnValue<signature> }
+              : {})
+        >
   >
 
   type ErrorType = Errors.GlobalErrorType

package/tempo/KeyAuthorization.ts

@@ -32,15 +32,16 @@ export type KeyAuthorization<
   signed extends boolean = boolean,
   bigintType = bigint,
   numberType = number,
+  addressType = Address.Address,
 > = {
   /** Address derived from the public key of the key type. */
-  address: TempoAddress.Address
+  address: addressType
   /** Chain ID for replay protection. */
   chainId: bigintType
   /** Unix timestamp when key expires (0 = never expires). */
   expiry?: numberType | null | undefined
   /** TIP20 spending limits for this key. */
-  limits?: readonly TokenLimit<bigintType>[] | undefined
+  limits?: readonly TokenLimit<bigintType, addressType>[] | undefined
   /** Key type. (secp256k1, P256, WebAuthn). */
   type: SignatureEnvelope.Type
 } & (signed extends true
@@ -51,6 +52,14 @@ export type KeyAuthorization<
         | undefined
     })
 
+/** Input type for a Key Authorization. */
+export type Input = KeyAuthorization<
+  false,
+  bigint,
+  number,
+  TempoAddress.Address
+>
+
 /** RPC representation of an {@link ox#KeyAuthorization.KeyAuthorization}. */
 export type Rpc = Omit<
   KeyAuthorization<false, Hex.Hex, Hex.Hex>,
@@ -62,11 +71,11 @@ export type Rpc = Omit<
 }
 
 /** Signed representation of a Key Authorization. */
-export type Signed<bigintType = bigint, numberType = number> = KeyAuthorization<
-  true,
-  bigintType,
-  numberType
->
+export type Signed<
+  bigintType = bigint,
+  numberType = number,
+  addressType = Address.Address,
+> = KeyAuthorization<true, bigintType, numberType, addressType>
 
 type BaseTuple = readonly [
   chainId: Hex.Hex,
@@ -106,9 +115,9 @@ export type Tuple<signed extends boolean = boolean> = signed extends true
  *
  * [Access Keys Specification](https://docs.tempo.xyz/protocol/transactions/spec-tempo-transaction#access-keys)
  */
-export type TokenLimit<bigintType = bigint> = {
+export type TokenLimit<bigintType = bigint, addressType = Address.Address> = {
   /** Address of the TIP-20 token. */
-  token: TempoAddress.Address
+  token: addressType
   /** Maximum spending amount for this token (enforced over the key's lifetime). */
   limit: bigintType
 }
@@ -250,7 +259,7 @@ export type TokenLimit<bigintType = bigint> = {
  * @returns The {@link ox#KeyAuthorization.KeyAuthorization}.
  */
 export function from<
-  const authorization extends KeyAuthorization | Rpc,
+  const authorization extends Input | Rpc,
   const signature extends SignatureEnvelope.from.Value | undefined = undefined,
 >(
   authorization: authorization | KeyAuthorization,
@@ -291,17 +300,19 @@ export declare namespace from {
   }
 
   type ReturnType<
-    authorization extends KeyAuthorization | Rpc = KeyAuthorization,
+    authorization extends KeyAuthorization | Input | Rpc = KeyAuthorization,
     signature extends SignatureEnvelope.from.Value | undefined =
       | SignatureEnvelope.from.Value
       | undefined,
   > = Compute<
     authorization extends Rpc
       ? Signed
-      : authorization &
-          (signature extends SignatureEnvelope.from.Value
-            ? { signature: SignatureEnvelope.from.ReturnValue<signature> }
-            : {})
+      : TempoAddress.ResolveAddresses<
+          authorization &
+            (signature extends SignatureEnvelope.from.Value
+              ? { signature: SignatureEnvelope.from.ReturnValue<signature> }
+              : {})
+        >
   >
 
   type ErrorType = Errors.GlobalErrorType

package/tempo/PoolId.ts

@@ -1,5 +1,6 @@
 import * as Hash from '../core/Hash.js'
 import * as Hex from '../core/Hex.js'
+import type * as TempoAddress from './TempoAddress.js'
 import * as TokenId from './TokenId.js'
 
 /**
@@ -35,8 +36,8 @@ export function from(value: from.Value): Hex.Hex {
 export declare namespace from {
   export type Value = {
     /** User token. */
-    userToken: TokenId.TokenIdOrAddress
+    userToken: TokenId.TokenIdOrAddress<TempoAddress.Address>
     /** Validator token. */
-    validatorToken: TokenId.TokenIdOrAddress
+    validatorToken: TokenId.TokenIdOrAddress<TempoAddress.Address>
   }
 }

package/tempo/TempoAddress.ts

@@ -9,6 +9,15 @@ export type Address = core_Address.Address | Tempo
 /** Root type for a Tempo Address. */
 export type Tempo = Compute<`tempox${string}`>
 
+/** Deeply converts all {@link ox#TempoAddress.Tempo} types to {@link ox#Address.Address}. */
+export type ResolveAddresses<type> = type extends Tempo
+  ? core_Address.Address
+  : type extends readonly (infer item)[]
+    ? readonly ResolveAddresses<item>[]
+    : type extends object
+      ? { [key in keyof type]: ResolveAddresses<type[key]> }
+      : type
+
 /**
  * Resolves an address input (either an Ethereum hex address or a Tempo address)
  * to an Ethereum hex address.

package/tempo/TokenId.ts

@@ -7,7 +7,9 @@ import * as TempoAddress from './TempoAddress.js'
 const tip20Prefix = '0x20c0'
 
 export type TokenId = bigint
-export type TokenIdOrAddress = TokenId | TempoAddress.Address
+export type TokenIdOrAddress<addressType = Address.Address> =
+  | TokenId
+  | addressType
 
 /**
  * Converts a token ID or address to a token ID.
@@ -73,7 +75,9 @@ export function fromAddress(address: TempoAddress.Address): TokenId {
  * @param tokenId - The token ID.
  * @returns The address.
  */
-export function toAddress(tokenId: TokenIdOrAddress): Address.Address {
+export function toAddress(
+  tokenId: TokenIdOrAddress<TempoAddress.Address>,
+): Address.Address {
   if (typeof tokenId === 'string') {
     const resolved = TempoAddress.resolve(tokenId as TempoAddress.Address)
     Address.assert(resolved)

package/tempo/TransactionRequest.ts

@@ -35,7 +35,7 @@ export type TransactionRequest<
     keyAuthorization?: KeyAuthorization.KeyAuthorization<true> | undefined
     keyData?: Hex.Hex | undefined
     keyType?: KeyType | undefined
-    feeToken?: TokenId.TokenIdOrAddress | undefined
+    feeToken?: TokenId.TokenIdOrAddress<TempoAddress.Address> | undefined
     nonceKey?: 'random' | bigintType | undefined
     validBefore?: numberType | undefined
     validAfter?: numberType | undefined

package/tempo/TxEnvelopeTempo.ts

@@ -69,6 +69,7 @@ export type TxEnvelopeTempo<
   bigintType = bigint,
   numberType = number,
   type extends string = Type,
+  addressType = Address.Address,
 > = Compute<
   {
     /** EIP-2930 Access List. */
@@ -78,11 +79,11 @@ export type TxEnvelopeTempo<
       | AuthorizationTempo.ListSigned<bigintType, numberType>
       | undefined
     /** Array of calls to execute. */
-    calls: readonly Call<bigintType, TempoAddress.Address>[]
+    calls: readonly Call<bigintType, addressType>[]
     /** EIP-155 Chain ID. */
     chainId: numberType
     /** Sender of the transaction. */
-    from?: TempoAddress.Address | undefined
+    from?: addressType | undefined
     /** Gas provided for transaction execution */
     gas?: bigintType | undefined
     /** Fee payer signature. */
@@ -100,7 +101,7 @@ export type TxEnvelopeTempo<
      * The authorization must be signed with the root key, the tx can be signed by the Keychain signature.
      */
     keyAuthorization?:
-      | KeyAuthorization.Signed<bigintType, numberType>
+      | KeyAuthorization.Signed<bigintType, numberType, addressType>
       | undefined
     /** Total fee per gas in wei (gasPrice/baseFeePerGas + maxPriorityFeePerGas). */
     maxFeePerGas?: bigintType | undefined
@@ -127,6 +128,15 @@ export type TxEnvelopeTempo<
       })
 >
 
+/** Input type that accepts TempoAddress for `calls.to`, `from`, etc. */
+export type Input = TxEnvelopeTempo<
+  boolean,
+  bigint,
+  number,
+  Type,
+  TempoAddress.Address
+>
+
 export type Rpc<signed extends boolean = boolean> = TxEnvelopeTempo<
   signed,
   Hex.Hex,
@@ -486,10 +496,10 @@ export declare namespace deserialize {
  * @returns A Tempo Transaction Envelope.
  */
 export function from<
-  const envelope extends UnionPartialBy<TxEnvelopeTempo, 'type'> | Serialized,
+  const envelope extends UnionPartialBy<Input, 'type'> | Serialized,
   const signature extends SignatureEnvelope.from.Value | undefined = undefined,
 >(
-  envelope: envelope | UnionPartialBy<TxEnvelopeTempo, 'type'> | Serialized,
+  envelope: envelope | UnionPartialBy<Input, 'type'> | Serialized,
   options: from.Options<signature> = {},
 ): from.ReturnValue<envelope, signature> {
   const { feePayerSignature, signature } = options
@@ -532,20 +542,22 @@ export declare namespace from {
   }
 
   type ReturnValue<
-    envelope extends UnionPartialBy<TxEnvelopeTempo, 'type'> | Hex.Hex =
+    envelope extends UnionPartialBy<Input, 'type'> | Hex.Hex =
       | TxEnvelopeTempo
       | Hex.Hex,
     signature extends SignatureEnvelope.from.Value | undefined = undefined,
   > = Compute<
     envelope extends Hex.Hex
       ? TxEnvelopeTempo
-      : Assign<
-          envelope,
-          (signature extends SignatureEnvelope.from.Value
-            ? { signature: SignatureEnvelope.from.ReturnValue<signature> }
-            : {}) & {
-            readonly type: 'tempo'
-          }
+      : TempoAddress.ResolveAddresses<
+          Assign<
+            envelope,
+            (signature extends SignatureEnvelope.from.Value
+              ? { signature: SignatureEnvelope.from.ReturnValue<signature> }
+              : {}) & {
+              readonly type: 'tempo'
+            }
+          >
         >
   >
 

package/version.ts

@@ -1,2 +1,2 @@
 /** @internal */
-export const version = '0.14.6'
+export const version = '0.14.8'