Add delegation encoding and decoding.

- Use these core methods in @metamask/delegation-toolkit

Author: jeffsmale90

packages/delegation-core/.eslintrc.cjs

@@ -1,6 +1,5 @@
 /** @type {import("eslint").Linter.Config} */
 module.exports = {
-  plugins: ['only-warn'],
   root: true,
   extends: ['../../shared/config/library.eslint.js'],
   parser: '@typescript-eslint/parser',

packages/delegation-core/package.json

@@ -60,5 +60,9 @@
     "tsup": "^7.2.0",
     "typescript": "5.0.4",
     "vitest": "^1.0.0"
+  },
+  "dependencies": {
+    "@metamask/abi-utils": "^3.0.0",
+    "@metamask/utils": "^11.4.0"
   }
 }

packages/delegation-core/src/delegation.ts

@@ -0,0 +1,146 @@
+import { encodeSingle, decodeSingle } from '@metamask/abi-utils';
+import { type BytesLike } from '@metamask/utils';
+
+import {
+  bytesLikeToBytes,
+  bytesLikeToHex,
+  defaultOptions,
+  prepareResult,
+  type EncodingOptions,
+  type ResultValue,
+} from './returns';
+import type { Delegation, Hex } from './types';
+
+/**
+ * To be used on a delegation as the root authority.
+ */
+export const ROOT_AUTHORITY =
+  '0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff';
+
+/**
+ * The ABI types for an array of delegations.
+ */
+const DELEGATION_ARRAY_ABI_TYPES =
+  '(address,address,bytes32,(address,bytes,bytes)[],uint256,bytes)[]' as const;
+
+/**
+ * Encodes an array of delegations into a permission context.
+ * @param delegations - The delegations to encode.
+ * @param options - Encoding options. Defaults to { out: 'hex' }.
+ * @returns The encoded delegations as a hex string (default) or Uint8Array.
+ */
+export function encodeDelegations(
+  delegations: Delegation[],
+  options?: EncodingOptions<'hex'>,
+): Hex;
+export function encodeDelegations(
+  delegations: Delegation[],
+  options: EncodingOptions<'bytes'>,
+): Uint8Array;
+export function encodeDelegations(
+  delegations: Delegation[],
+  options: EncodingOptions<ResultValue> = defaultOptions,
+): Hex | Uint8Array {
+  let result: Uint8Array;
+
+  if (delegations.length === 0) {
+    // short circuit for empty delegations, derived from
+    // `encode(['(address,address,bytes32,(address,bytes,bytes)[],uint256,bytes)[]'],[[]],);`
+    result = new Uint8Array(64);
+    result[31] = 0x20;
+  } else {
+    const encodableStructs = delegations.map((struct) => [
+      struct.delegate,
+      struct.delegator,
+      struct.authority,
+      struct.caveats.map((caveat) => [
+        caveat.enforcer,
+        caveat.terms,
+        caveat.args,
+      ]),
+      struct.salt,
+      struct.signature,
+    ]);
+
+    result = encodeSingle(DELEGATION_ARRAY_ABI_TYPES, encodableStructs);
+  }
+
+  return prepareResult(result, options);
+}
+
+/**
+ * Represents a decoded delegation as a tuple structure.
+ * This type defines the structure of a delegation after it has been decoded from
+ * an encoded format.
+ */
+type DecodedDelegation = [
+  BytesLike,
+  BytesLike,
+  BytesLike,
+  [BytesLike, BytesLike, BytesLike][],
+  bigint,
+  BytesLike,
+];
+
+/**
+ * Decodes an encoded permission context back into an array of delegations.
+ * @param encoded - The encoded delegations as a hex string or Uint8Array.
+ * @param options - Encoding options. Defaults to { out: 'hex' }.
+ * @returns The decoded delegations array with types resolved based on options.
+ */
+export function decodeDelegations(
+  encoded: BytesLike,
+  options?: EncodingOptions<'hex'>,
+): Delegation<Hex>[];
+export function decodeDelegations(
+  encoded: BytesLike,
+  options: EncodingOptions<'bytes'>,
+): Delegation<Uint8Array>[];
+export function decodeDelegations(
+  encoded: BytesLike,
+  options: EncodingOptions<ResultValue> = defaultOptions,
+): Delegation<Hex>[] | Delegation<Uint8Array>[] {
+  // it's possible to short circuit for empty delegations, but due to the
+  // complexity of the input type, and the relative infrequency of empty delegations,
+  // it's not worthwhile.
+
+  const decodedStructs = decodeSingle(
+    DELEGATION_ARRAY_ABI_TYPES,
+    encoded,
+    // return types cannot be inferred from complex ABI types, so we must assert the type
+  ) as DecodedDelegation[];
+
+  if (options.out === 'bytes') {
+    return decodedStructs.map((struct) =>
+      delegationFromDecodedDelegation(struct, bytesLikeToBytes),
+    );
+  } else {
+    return decodedStructs.map((struct) =>
+      delegationFromDecodedDelegation(struct, bytesLikeToHex),
+    );
+  }
+}
+
+/**
+ * Converts a decoded delegation struct to a delegation object using the provided conversion function.
+ * @param decodedDelegation - The decoded delegation struct as a tuple.
+ * @param convertFn - Function to convert BytesLike values to the desired output type.
+ * @returns A delegation object with all bytes-like values converted using the provided function.
+ */
+const delegationFromDecodedDelegation = <T extends BytesLike>(
+  [delegate, delegator, authority, caveats, salt, signature]: DecodedDelegation,
+  convertFn: (value: BytesLike) => T,
+): Delegation<T> => {
+  return {
+    delegate: convertFn(delegate),
+    delegator: convertFn(delegator),
+    authority: convertFn(authority),
+    caveats: caveats.map(([enforcer, terms, args]) => ({
+      enforcer: convertFn(enforcer),
+      terms: convertFn(terms),
+      args: convertFn(args),
+    })),
+    salt,
+    signature: convertFn(signature),
+  };
+};

packages/delegation-core/src/index.ts

@@ -1,4 +1,4 @@
-export type { Hex } from './types';
+export type { Hex, Delegation, Caveat } from './types';
 
 export {
   createValueLteTerms,
@@ -7,3 +7,9 @@ export {
   createExactCalldataTerms,
   createNativeTokenStreamingTerms,
 } from './caveats';
+
+export {
+  encodeDelegations,
+  decodeDelegations,
+  ROOT_AUTHORITY,
+} from './delegation';

packages/delegation-core/src/returns.ts

@@ -0,0 +1,68 @@
+import { type BytesLike, bytesToHex, hexToBytes } from '@metamask/utils';
+
+import type { Hex } from './types';
+
+/**
+ * The possible return value types for encoding/decoding operations.
+ */
+export type ResultValue = 'hex' | 'bytes';
+
+/**
+ * Utility type for function return types based on ResultValue.
+ */
+export type ResultType<TResultValue extends ResultValue> =
+  TResultValue extends 'hex' ? Hex : Uint8Array;
+
+/**
+ * Base options interface for operations that can return hex or bytes.
+ */
+export type EncodingOptions<TResultValue extends ResultValue> = {
+  out: TResultValue;
+};
+
+/**
+ * Default options value with proper typing. Use this as your default parameter.
+ */
+export const defaultOptions = { out: 'hex' } as EncodingOptions<any>;
+
+/**
+ * Prepares a result by converting between hex and bytes based on options.
+ * @param result - The value to convert (either Uint8Array or Hex).
+ * @param options - The options specifying the desired output format.
+ * @returns The converted value with proper type narrowing.
+ */
+export function prepareResult<TResultValue extends ResultValue>(
+  result: Uint8Array | Hex,
+  options: EncodingOptions<TResultValue>,
+): ResultType<TResultValue> {
+  if (options.out === 'hex') {
+    const hexValue = typeof result === 'string' ? result : bytesToHex(result);
+    return hexValue as ResultType<TResultValue>;
+  }
+  const bytesValue = result instanceof Uint8Array ? result : hexToBytes(result);
+  return bytesValue as ResultType<TResultValue>;
+}
+
+/**
+ * Converts a bytes-like value to a hex string.
+ * @param bytesLike - The bytes-like value to convert.
+ * @returns The hex string representation of the bytes-like value.
+ */
+export const bytesLikeToHex = (bytesLike: BytesLike) => {
+  if (typeof bytesLike === 'string') {
+    return bytesLike;
+  }
+  return bytesToHex(bytesLike);
+};
+
+/**
+ * Converts a bytes-like value to a Uint8Array.
+ * @param bytesLike - The bytes-like value to convert.
+ * @returns The Uint8Array representation of the bytes-like value.
+ */
+export const bytesLikeToBytes = (bytesLike: BytesLike) => {
+  if (typeof bytesLike === 'string') {
+    return hexToBytes(bytesLike);
+  }
+  return bytesLike;
+};

packages/delegation-core/src/types.ts

@@ -1,4 +1,35 @@
+import type { BytesLike } from '@metamask/utils';
+
+export type { Hex } from '@metamask/utils';
+
 /**
- * A hex value - a "0x"-prefixed string.
+ * Represents a caveat that restricts or conditions a delegation.
+ *
+ * @property enforcer - The address of the contract that enforces this caveat's conditions.
+ * @property terms - The terms or conditions of the caveat encoded as hex data.
+ * @property args - Additional arguments required by the caveat enforcer, encoded as hex data.
  */
-export type Hex = `0x${string}`;
+export type Caveat<TBytes extends BytesLike = BytesLike> = {
+  enforcer: TBytes;
+  terms: TBytes;
+  args: TBytes;
+};
+
+/**
+ * Represents a delegation that grants permissions from a delegator to a delegate.
+ *
+ * @property delegate - The address of the entity receiving the delegation.
+ * @property delegator - The address of the entity granting the delegation.
+ * @property authority - The authority under which this delegation is granted. For root delegations, this is ROOT_AUTHORITY.
+ * @property caveats - An array of restrictions or conditions applied to this delegation.
+ * @property salt - A unique value to prevent replay attacks and ensure uniqueness of the delegation.
+ * @property signature - The cryptographic signature validating this delegation.
+ */
+export type Delegation<TBytes extends BytesLike = BytesLike> = {
+  delegate: TBytes;
+  delegator: TBytes;
+  authority: TBytes;
+  caveats: Caveat<TBytes>[];
+  salt: bigint;
+  signature: TBytes;
+};