ox 0.14.26 → 0.14.28

package/tempo/ReceivePolicyReceipt.ts

@@ -0,0 +1,263 @@
+import * as AbiEvent from '../core/AbiEvent.js'
+import * as AbiParameters from '../core/AbiParameters.js'
+import type * as Address from '../core/Address.js'
+import type * as Errors from '../core/Errors.js'
+import type * as Hex from '../core/Hex.js'
+import type { Compute } from '../core/internal/types.js'
+
+/**
+ * A TIP-1028 receive-policy claim receipt: the ABI-encoded `ClaimReceiptV1`
+ * witness emitted when an inbound transfer or mint violates the recipient's
+ * receive policy.
+ *
+ * This is the canonical, on-chain representation – the value passed to the
+ * `ReceivePolicyGuard`'s `claim` and `burn` functions. Use `decode` to read its
+ * fields.
+ */
+export type ReceivePolicyReceipt = Hex.Hex
+
+/** Reason an inbound transfer or mint was blocked by a receive policy. */
+export type BlockedReason = 'none' | 'tokenFilter' | 'receivePolicy'
+
+/** Kind of inbound operation that was blocked. */
+export type Kind = 'transfer' | 'mint'
+
+/** A decoded {@link ox#ReceivePolicyReceipt.ReceivePolicyReceipt}. */
+export type Decoded = Compute<{
+  /** Receipt layout version. */
+  version: number
+  /** TIP-20 token holding the blocked funds. */
+  token: Address.Address
+  /** Recovery authority captured when the operation was blocked. */
+  recoveryAuthority: Address.Address
+  /** Original sender (transfer) or issuer (mint). */
+  originator: Address.Address
+  /** Addressed recipient (may be a virtual address). */
+  recipient: Address.Address
+  /** Block timestamp when the operation was blocked. */
+  blockedAt: bigint
+  /** Guard nonce assigned when the operation was blocked. */
+  blockedNonce: bigint
+  /** Reason the operation was blocked. */
+  blockedReason: BlockedReason
+  /** Whether the blocked operation was a transfer or mint. */
+  kind: Kind
+  /** Application memo. */
+  memo: Hex.Hex
+}>
+
+/** @internal */
+const blockedReasons = ['none', 'tokenFilter', 'receivePolicy'] as const
+
+/** @internal */
+const kinds = ['transfer', 'mint'] as const
+
+/** @internal ABI parameters for the `ClaimReceiptV1` witness. */
+const parameters = [
+  {
+    type: 'tuple',
+    components: [
+      { name: 'version', type: 'uint8' },
+      { name: 'token', type: 'address' },
+      { name: 'recoveryAuthority', type: 'address' },
+      { name: 'originator', type: 'address' },
+      { name: 'recipient', type: 'address' },
+      { name: 'blockedAt', type: 'uint64' },
+      { name: 'blockedNonce', type: 'uint64' },
+      { name: 'blockedReason', type: 'uint8' },
+      { name: 'kind', type: 'uint8' },
+      { name: 'memo', type: 'bytes32' },
+    ],
+  },
+] as const
+
+/** @internal `TransferBlocked` event emitted by the `ReceivePolicyGuard`. */
+const transferBlocked = AbiEvent.from(
+  'event TransferBlocked(address indexed token, address indexed receiver, uint64 indexed blockedNonce, uint256 amount, uint8 receiptVersion, bytes receipt)',
+)
+
+/**
+ * Decodes a {@link ox#ReceivePolicyReceipt.ReceivePolicyReceipt} (ABI-encoded
+ * `ClaimReceiptV1` witness) into its fields.
+ *
+ * [TIP-1028](https://docs.tempo.xyz/protocol/tips/tip-1028)
+ *
+ * @example
+ * ```ts twoslash
+ * import { ReceivePolicyReceipt } from 'ox/tempo'
+ *
+ * const decoded = ReceivePolicyReceipt.decode('0x...')
+ * ```
+ *
+ * @param receipt - The receive-policy receipt.
+ * @returns The decoded fields.
+ */
+export function decode(receipt: ReceivePolicyReceipt): Decoded {
+  const [decoded] = AbiParameters.decode(parameters, receipt)
+  return {
+    version: decoded.version,
+    token: decoded.token,
+    recoveryAuthority: decoded.recoveryAuthority,
+    originator: decoded.originator,
+    recipient: decoded.recipient,
+    blockedAt: decoded.blockedAt,
+    blockedNonce: decoded.blockedNonce,
+    blockedReason: blockedReasons[decoded.blockedReason] ?? 'none',
+    kind: kinds[decoded.kind] ?? 'transfer',
+    memo: decoded.memo,
+  }
+}
+
+export declare namespace decode {
+  type ErrorType = AbiParameters.decode.ErrorType | Errors.GlobalErrorType
+}
+
+/**
+ * Encodes decoded fields into a
+ * {@link ox#ReceivePolicyReceipt.ReceivePolicyReceipt}. Inverse of `decode`.
+ *
+ * [TIP-1028](https://docs.tempo.xyz/protocol/tips/tip-1028)
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { ReceivePolicyReceipt } from 'ox/tempo'
+ *
+ * const decoded = ReceivePolicyReceipt.decode('0x...')
+ * const receipt = ReceivePolicyReceipt.encode(decoded)
+ * ```
+ *
+ * @param decoded - The decoded fields.
+ * @returns The receive-policy receipt.
+ */
+export function encode(decoded: Decoded): ReceivePolicyReceipt {
+  return AbiParameters.encode(parameters, [
+    {
+      version: decoded.version,
+      token: decoded.token,
+      recoveryAuthority: decoded.recoveryAuthority,
+      originator: decoded.originator,
+      recipient: decoded.recipient,
+      blockedAt: decoded.blockedAt,
+      blockedNonce: decoded.blockedNonce,
+      blockedReason: blockedReasons.indexOf(decoded.blockedReason),
+      kind: kinds.indexOf(decoded.kind),
+      memo: decoded.memo,
+    },
+  ])
+}
+
+export declare namespace encode {
+  type ErrorType = AbiParameters.encode.ErrorType | Errors.GlobalErrorType
+}
+
+/**
+ * Normalizes a {@link ox#ReceivePolicyReceipt.ReceivePolicyReceipt} from either
+ * an encoded receipt (passthrough) or decoded fields.
+ *
+ * [TIP-1028](https://docs.tempo.xyz/protocol/tips/tip-1028)
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { ReceivePolicyReceipt } from 'ox/tempo'
+ *
+ * // From an encoded receipt (passthrough).
+ * const a = ReceivePolicyReceipt.from('0x...')
+ *
+ * // From decoded fields.
+ * const b = ReceivePolicyReceipt.from(ReceivePolicyReceipt.decode('0x...'))
+ * ```
+ *
+ * @param value - An encoded receipt or decoded fields.
+ * @returns The receive-policy receipt.
+ */
+export function from(
+  value: ReceivePolicyReceipt | Decoded,
+): ReceivePolicyReceipt {
+  if (typeof value === 'string') return value
+  return encode(value)
+}
+
+export declare namespace from {
+  type ErrorType = encode.ErrorType | Errors.GlobalErrorType
+}
+
+/**
+ * Extracts the {@link ox#ReceivePolicyReceipt.ReceivePolicyReceipt} from a
+ * `ReceivePolicyGuard` `TransferBlocked` log.
+ *
+ * Throws if the log is not a `TransferBlocked` event. Use
+ * `fromTransactionReceipt` to extract every blocked transfer in a transaction
+ * (which skips unrelated logs).
+ *
+ * [TIP-1028](https://docs.tempo.xyz/protocol/tips/tip-1028)
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { ReceivePolicyReceipt } from 'ox/tempo'
+ *
+ * const receipt = ReceivePolicyReceipt.fromLog(log)
+ * ```
+ *
+ * @param log - A `TransferBlocked` log (`data` & `topics`).
+ * @returns The receive-policy receipt.
+ */
+export function fromLog(log: fromLog.Log): ReceivePolicyReceipt {
+  const { receipt } = AbiEvent.decode(transferBlocked, log)
+  return receipt
+}
+
+export declare namespace fromLog {
+  type Log = AbiEvent.decode.Log
+
+  type ErrorType = AbiEvent.decode.ErrorType | Errors.GlobalErrorType
+}
+
+/**
+ * Extracts every {@link ox#ReceivePolicyReceipt.ReceivePolicyReceipt} from a
+ * transaction receipt's logs.
+ *
+ * A single transaction may block multiple inbound transfers (e.g. a batched
+ * transfer to several recipients), so this returns an array – one entry per
+ * `TransferBlocked` log, in log order. Returns an empty array when no transfers
+ * were blocked.
+ *
+ * [TIP-1028](https://docs.tempo.xyz/protocol/tips/tip-1028)
+ *
+ * @example
+ * ```ts twoslash
+ * // @noErrors
+ * import { ReceivePolicyReceipt } from 'ox/tempo'
+ *
+ * const receipts = ReceivePolicyReceipt.fromTransactionReceipt(receipt)
+ * // @log: ['0x...'] (pass each to `claim` / `burn`)
+ * ```
+ *
+ * @param receipt - The transaction receipt (or any object with `logs`).
+ * @returns The receive-policy receipts, one per blocked transfer.
+ */
+export function fromTransactionReceipt(
+  receipt: fromTransactionReceipt.Receipt,
+): readonly ReceivePolicyReceipt[] {
+  const selector = AbiEvent.getSelector(transferBlocked)
+  const receipts: ReceivePolicyReceipt[] = []
+  for (const log of receipt.logs ?? []) {
+    if (log.topics[0] !== selector) continue
+    receipts.push(fromLog(log))
+  }
+  return receipts
+}
+
+export declare namespace fromTransactionReceipt {
+  type Receipt = {
+    /** Logs emitted by the transaction. */
+    logs?: readonly AbiEvent.decode.Log[] | undefined
+  }
+
+  type ErrorType =
+    | AbiEvent.getSelector.ErrorType
+    | fromLog.ErrorType
+    | Errors.GlobalErrorType
+}

package/tempo/SignatureEnvelope.test.ts

@@ -9,6 +9,7 @@ import {
   WebCryptoP256,
 } from 'ox'
 import { describe, expect, test } from 'vitest'
+import * as MultisigConfig from './MultisigConfig.js'
 import * as SignatureEnvelope from './SignatureEnvelope.js'
 
 const publicKey = PublicKey.from({
@@ -512,7 +513,7 @@ describe('deserialize', () => {
         SignatureEnvelope.deserialize('0xdeadbeef'),
       ).toThrowErrorMatchingInlineSnapshot(
         `
-        [SignatureEnvelope.InvalidSerializedError: Unable to deserialize signature envelope: Unknown signature type identifier: 0xde. Expected 0x01 (P256), 0x02 (WebAuthn), 0x03 (Keychain V1), or 0x04 (Keychain V2)
+        [SignatureEnvelope.InvalidSerializedError: Unable to deserialize signature envelope: Unknown signature type identifier: 0xde. Expected 0x01 (P256), 0x02 (WebAuthn), 0x03 (Keychain V1), 0x04 (Keychain V2), or 0x05 (Multisig)
 
         Serialized: 0xdeadbeef]
       `,
@@ -672,7 +673,7 @@ describe('deserialize', () => {
         SignatureEnvelope.deserialize(unknownType),
       ).toThrowErrorMatchingInlineSnapshot(
         `
-        [SignatureEnvelope.InvalidSerializedError: Unable to deserialize signature envelope: Unknown signature type identifier: 0xff. Expected 0x01 (P256), 0x02 (WebAuthn), 0x03 (Keychain V1), or 0x04 (Keychain V2)
+        [SignatureEnvelope.InvalidSerializedError: Unable to deserialize signature envelope: Unknown signature type identifier: 0xff. Expected 0x01 (P256), 0x02 (WebAuthn), 0x03 (Keychain V1), 0x04 (Keychain V2), or 0x05 (Multisig)
 
         Serialized: 0xff000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000]
       `,
@@ -1696,6 +1697,67 @@ describe('serialize', () => {
   })
 })
 
+describe('sortMultisigApprovals', () => {
+  const account = '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' as const
+  const configId = `0x${'11'.repeat(32)}` as const
+  const payload = `0x${'42'.repeat(32)}` as const
+  const digest = MultisigConfig.getSignPayload({
+    account,
+    configId,
+    payload,
+  })
+
+  const owners = Array.from({ length: 3 }, () => {
+    const privateKey = Secp256k1.randomPrivateKey()
+    const address = Address.fromPublicKey(
+      Secp256k1.getPublicKey({ privateKey }),
+    )
+    const signature = SignatureEnvelope.from(
+      Secp256k1.sign({ payload: digest, privateKey }),
+    )
+    return { address, signature } as const
+  })
+  const ascending = [...owners].sort((a, b) =>
+    Hex.toBigInt(a.address) < Hex.toBigInt(b.address) ? -1 : 1,
+  )
+
+  test('behavior: orders approvals ascending by recovered owner address', () => {
+    const ordered = SignatureEnvelope.sortMultisigApprovals({
+      account,
+      configId,
+      payload,
+      // Provide approvals in reverse of the canonical order.
+      signatures: [...ascending].reverse().map((owner) => owner.signature),
+    })
+    expect(ordered).toEqual(ascending.map((owner) => owner.signature))
+  })
+
+  test('behavior: already-sorted input is unchanged', () => {
+    const signatures = ascending.map((owner) => owner.signature)
+    expect(
+      SignatureEnvelope.sortMultisigApprovals({
+        account,
+        configId,
+        payload,
+        signatures,
+      }),
+    ).toEqual(signatures)
+  })
+
+  test('behavior: recovered order matches the config owner order', () => {
+    const ordered = SignatureEnvelope.sortMultisigApprovals({
+      account,
+      configId,
+      payload,
+      signatures: owners.map((owner) => owner.signature),
+    })
+    const recovered = ordered.map((signature) =>
+      SignatureEnvelope.extractAddress({ payload: digest, signature }),
+    )
+    expect(recovered).toEqual(ascending.map((owner) => owner.address))
+  })
+})
+
 describe('validate', () => {
   describe('secp256k1', () => {
     test('behavior: returns true for valid signature', () => {
@@ -2692,3 +2754,152 @@ describe('CoercionError', () => {
     )
   })
 })
+
+describe('multisig', () => {
+  const account = '0x8ba6d26ff5c4e82ba0c8caf8c8ca794e1489a7ae'
+  const configId =
+    '0x01781fe551182476f2422c759e82d81c92e3263737afbbad57def6e8b69d21f5'
+
+  // P256 signatures do not carry `yParity` in the wire format, so use a clean
+  // inner signature for round-trip equality checks.
+  const innerP256 = SignatureEnvelope.from({
+    signature: { r: p256Signature.r, s: p256Signature.s },
+    publicKey,
+    prehash: true,
+  })
+
+  const envelope = SignatureEnvelope.from({
+    type: 'multisig',
+    account,
+    configId,
+    signatures: [SignatureEnvelope.from(signature_secp256k1), innerP256],
+  })
+
+  test('serialize: type byte 0x05 prefix', () => {
+    const serialized = SignatureEnvelope.serialize(envelope)
+    expect(serialized.startsWith('0x05')).toBe(true)
+  })
+
+  test('serialize/deserialize round-trip', () => {
+    const serialized = SignatureEnvelope.serialize(envelope)
+    expect(SignatureEnvelope.deserialize(serialized)).toEqual(envelope)
+  })
+
+  test('getType', () => {
+    expect(SignatureEnvelope.getType(envelope)).toBe('multisig')
+  })
+
+  test('extractAddress returns the multisig account', () => {
+    expect(
+      SignatureEnvelope.extractAddress({
+        payload: '0xdeadbeef',
+        signature: envelope,
+      }),
+    ).toBe(account)
+  })
+
+  test('toRpc/fromRpc round-trip', () => {
+    const rpc = SignatureEnvelope.toRpc(envelope)
+    expect(rpc.type).toBe('multisig')
+    expect(SignatureEnvelope.fromRpc(rpc)).toEqual(envelope)
+  })
+
+  test('assert: missing properties', () => {
+    expect(() =>
+      SignatureEnvelope.assert({ type: 'multisig', account } as never),
+    ).toThrowError()
+  })
+
+  describe('init (bootstrap)', () => {
+    const init = {
+      salt: `0x${'00'.repeat(32)}` as const,
+      threshold: 1,
+      owners: [
+        {
+          owner: '0x1111111111111111111111111111111111111111' as const,
+          weight: 1,
+        },
+      ],
+    }
+
+    const bootstrapEnvelope = SignatureEnvelope.from({
+      type: 'multisig',
+      account,
+      configId,
+      signatures: [SignatureEnvelope.from(signature_secp256k1), innerP256],
+      init,
+    })
+
+    test('serialize/deserialize round-trip with init', () => {
+      const serialized = SignatureEnvelope.serialize(bootstrapEnvelope)
+      expect(SignatureEnvelope.deserialize(serialized)).toEqual(
+        bootstrapEnvelope,
+      )
+    })
+
+    test('serialize/deserialize round-trip preserves non-zero salt', () => {
+      const salted = SignatureEnvelope.from({
+        type: 'multisig',
+        account,
+        configId,
+        signatures: [SignatureEnvelope.from(signature_secp256k1), innerP256],
+        init: { ...init, salt: `0x${'42'.repeat(32)}` },
+      })
+      const serialized = SignatureEnvelope.serialize(salted)
+      const deserialized = SignatureEnvelope.deserialize(
+        serialized,
+      ) as SignatureEnvelope.Multisig
+      expect(deserialized.init?.salt).toBe(`0x${'42'.repeat(32)}`)
+      expect(deserialized).toEqual(salted)
+    })
+
+    test('absent init has no `init` key after deserialize', () => {
+      const serialized = SignatureEnvelope.serialize(envelope)
+      const deserialized = SignatureEnvelope.deserialize(serialized)
+      expect('init' in deserialized).toBe(false)
+    })
+
+    test('init absent vs present produce different serializations', () => {
+      expect(SignatureEnvelope.serialize(envelope)).not.toBe(
+        SignatureEnvelope.serialize(bootstrapEnvelope),
+      )
+    })
+
+    test('toRpc/fromRpc round-trip with init', () => {
+      const rpc = SignatureEnvelope.toRpc(bootstrapEnvelope)
+      expect(rpc.init).toEqual(init)
+      expect(SignatureEnvelope.fromRpc(rpc)).toEqual(bootstrapEnvelope)
+    })
+
+    test('toRpc encodes owner approvals as serialized hex (node `Vec<Bytes>`)', () => {
+      const multisig = bootstrapEnvelope as SignatureEnvelope.Multisig
+      const rpc = SignatureEnvelope.toRpc(
+        multisig,
+      ) as SignatureEnvelope.MultisigRpc
+      expect(rpc.signatures).toEqual(
+        multisig.signatures.map((s) => SignatureEnvelope.serialize(s)),
+      )
+    })
+
+    test('fromRpc detects multisig by shape (no `type` field)', () => {
+      const rpc = SignatureEnvelope.toRpc(bootstrapEnvelope)
+      // The node omits the `type` discriminant; detection is shape-based.
+      const { type: _type, ...untyped } = rpc
+      expect(SignatureEnvelope.fromRpc(untyped as never)).toEqual(
+        bootstrapEnvelope,
+      )
+    })
+
+    test('assert: invalid init config throws', () => {
+      expect(() =>
+        SignatureEnvelope.assert({
+          type: 'multisig',
+          account,
+          configId,
+          signatures: [],
+          init: { threshold: 1, owners: [] },
+        } as never),
+      ).toThrowError()
+    })
+  })
+})