@metamask/gator-permissions-controller 0.1.0 → 0.2.1

package/dist/decodePermission/decodePermission.mjs

@@ -0,0 +1,190 @@
+import { ROOT_AUTHORITY } from "@metamask/delegation-core";
+import { getChecksumAddress, hexToNumber, numberToHex } from "@metamask/utils";
+import { createPermissionRulesForChainId, getChecksumEnforcersByChainId, getTermsByEnforcer, isSubset, splitHex } from "./utils.mjs";
+/**
+ * Identifies the unique permission type that matches a given set of enforcer
+ * contract addresses for a specific chain.
+ *
+ * A permission type matches when:
+ * - All of its required enforcers are present in the provided list; and
+ * - No provided enforcer falls outside the union of the type's required and
+ * allowed enforcers (currently only `TimestampEnforcer` is allowed extra).
+ *
+ * If exactly one permission type matches, its identifier is returned.
+ *
+ * @param args - The arguments to this function.
+ * @param args.enforcers - List of enforcer contract addresses (hex strings).
+ *
+ * @param args.contracts - The deployed contracts for the chain.
+ * @returns The identifier of the matching permission type.
+ * @throws If no permission type matches, or if more than one permission type matches.
+ */
+export const identifyPermissionByEnforcers = ({ enforcers, contracts, }) => {
+    const enforcersSet = new Set(enforcers.map(getChecksumAddress));
+    const permissionRules = createPermissionRulesForChainId(contracts);
+    let matchingPermissionType = null;
+    for (const { allowedEnforcers, requiredEnforcers, permissionType, } of permissionRules) {
+        const hasAllRequiredEnforcers = isSubset(requiredEnforcers, enforcersSet);
+        let hasForbiddenEnforcers = false;
+        for (const caveat of enforcersSet) {
+            if (!allowedEnforcers.has(caveat) && !requiredEnforcers.has(caveat)) {
+                hasForbiddenEnforcers = true;
+                break;
+            }
+        }
+        if (hasAllRequiredEnforcers && !hasForbiddenEnforcers) {
+            if (matchingPermissionType) {
+                throw new Error('Multiple permission types match');
+            }
+            matchingPermissionType = permissionType;
+        }
+    }
+    if (!matchingPermissionType) {
+        throw new Error('Unable to identify permission type');
+    }
+    return matchingPermissionType;
+};
+/**
+ * Extracts the permission-specific data payload and the expiry timestamp from
+ * the provided caveats for a given permission type.
+ *
+ * This function locates the relevant caveat enforcer for the `permissionType`,
+ * interprets its `terms` by splitting the hex string into byte-sized segments,
+ * and converts each segment into the appropriate numeric or address shape.
+ *
+ * The expiry timestamp is derived from the `TimestampEnforcer` terms and must
+ * have a zero `timestampAfterThreshold` and a positive `timestampBeforeThreshold`.
+ *
+ * @param args - The arguments to this function.
+ * @param args.contracts - The deployed contracts for the chain.
+ * @param args.caveats - Caveats decoded from the permission context.
+ * @param args.permissionType - The previously identified permission type.
+ *
+ * @returns An object containing the `expiry` timestamp and the decoded `data` payload.
+ * @throws If the caveats are malformed, missing, or the terms fail to decode.
+ */
+export const getPermissionDataAndExpiry = ({ contracts, caveats, permissionType, }) => {
+    const checksumCaveats = caveats.map((caveat) => ({
+        ...caveat,
+        enforcer: getChecksumAddress(caveat.enforcer),
+    }));
+    const { erc20StreamingEnforcer, erc20PeriodicEnforcer, nativeTokenStreamingEnforcer, nativeTokenPeriodicEnforcer, timestampEnforcer, } = getChecksumEnforcersByChainId(contracts);
+    const expiryTerms = getTermsByEnforcer({
+        caveats: checksumCaveats,
+        enforcer: timestampEnforcer,
+        throwIfNotFound: false,
+    });
+    let expiry = null;
+    if (expiryTerms) {
+        const [after, before] = splitHex(expiryTerms, [16, 16]);
+        if (hexToNumber(after) !== 0) {
+            throw new Error('Invalid expiry');
+        }
+        expiry = hexToNumber(before);
+    }
+    let data;
+    switch (permissionType) {
+        case 'erc20-token-stream': {
+            const erc20StreamingTerms = getTermsByEnforcer({
+                caveats: checksumCaveats,
+                enforcer: erc20StreamingEnforcer,
+            });
+            const [tokenAddress, initialAmount, maxAmount, amountPerSecond, startTimeRaw,] = splitHex(erc20StreamingTerms, [20, 32, 32, 32, 32]);
+            data = {
+                tokenAddress,
+                initialAmount,
+                maxAmount,
+                amountPerSecond,
+                startTime: hexToNumber(startTimeRaw),
+            };
+            break;
+        }
+        case 'erc20-token-periodic': {
+            const erc20PeriodicTerms = getTermsByEnforcer({
+                caveats: checksumCaveats,
+                enforcer: erc20PeriodicEnforcer,
+            });
+            const [tokenAddress, periodAmount, periodDurationRaw, startTimeRaw] = splitHex(erc20PeriodicTerms, [20, 32, 32, 32]);
+            data = {
+                tokenAddress,
+                periodAmount,
+                periodDuration: hexToNumber(periodDurationRaw),
+                startTime: hexToNumber(startTimeRaw),
+            };
+            break;
+        }
+        case 'native-token-stream': {
+            const nativeTokenStreamingTerms = getTermsByEnforcer({
+                caveats: checksumCaveats,
+                enforcer: nativeTokenStreamingEnforcer,
+            });
+            const [initialAmount, maxAmount, amountPerSecond, startTimeRaw] = splitHex(nativeTokenStreamingTerms, [32, 32, 32, 32]);
+            data = {
+                initialAmount,
+                maxAmount,
+                amountPerSecond,
+                startTime: hexToNumber(startTimeRaw),
+            };
+            break;
+        }
+        case 'native-token-periodic': {
+            const nativeTokenPeriodicTerms = getTermsByEnforcer({
+                caveats: checksumCaveats,
+                enforcer: nativeTokenPeriodicEnforcer,
+            });
+            const [periodAmount, periodDurationRaw, startTimeRaw] = splitHex(nativeTokenPeriodicTerms, [32, 32, 32]);
+            data = {
+                periodAmount,
+                periodDuration: hexToNumber(periodDurationRaw),
+                startTime: hexToNumber(startTimeRaw),
+            };
+            break;
+        }
+        default:
+            throw new Error('Invalid permission type');
+    }
+    return { expiry, data };
+};
+/**
+ * Reconstructs a {@link DecodedPermission} object from primitive values
+ * obtained while decoding a permission context.
+ *
+ * The resulting object contains:
+ * - `chainId` encoded as hex (`0x…`)
+ * - `address` set to the delegator (user account)
+ * - `signer` set to an account signer with the delegate address
+ * - `permission` with the identified type and decoded data
+ * - `expiry` timestamp (or null)
+ *
+ * @param args - The arguments to this function.
+ * @param args.chainId - Chain ID.
+ * @param args.permissionType - Identified permission type.
+ * @param args.delegator - Address of the account delegating permission.
+ * @param args.delegate - Address that will act under the granted permission.
+ * @param args.authority - Authority identifier; must be ROOT_AUTHORITY.
+ * @param args.expiry - Expiry timestamp (unix seconds) or null if unbounded.
+ * @param args.data - Permission-specific decoded data payload.
+ * @param args.justification - Human-readable justification for the permission.
+ * @param args.specifiedOrigin - The origin reported in the request metadata.
+ *
+ * @returns The reconstructed {@link DecodedPermission}.
+ */
+export const reconstructDecodedPermission = ({ chainId, permissionType, delegator, delegate, authority, expiry, data, justification, specifiedOrigin, }) => {
+    if (authority !== ROOT_AUTHORITY) {
+        throw new Error('Invalid authority');
+    }
+    const permission = {
+        chainId: numberToHex(chainId),
+        address: delegator,
+        signer: { type: 'account', data: { address: delegate } },
+        permission: {
+            type: permissionType,
+            data,
+            justification,
+        },
+        expiry,
+        origin: specifiedOrigin,
+    };
+    return permission;
+};
+//# sourceMappingURL=decodePermission.mjs.map

package/dist/decodePermission/decodePermission.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"decodePermission.mjs","sourceRoot":"","sources":["../../src/decodePermission/decodePermission.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Caveat, Hex } from '@metamask/delegation-core';\nimport { ROOT_AUTHORITY } from '@metamask/delegation-core';\nimport { getChecksumAddress, hexToNumber, numberToHex } from '@metamask/utils';\n\nimport type {\n  DecodedPermission,\n  DeployedContractsByName,\n  PermissionType,\n} from './types';\nimport {\n  createPermissionRulesForChainId,\n  getChecksumEnforcersByChainId,\n  getTermsByEnforcer,\n  isSubset,\n  splitHex,\n} from './utils';\n\n/**\n * Identifies the unique permission type that matches a given set of enforcer\n * contract addresses for a specific chain.\n *\n * A permission type matches when:\n * - All of its required enforcers are present in the provided list; and\n * - No provided enforcer falls outside the union of the type's required and\n * allowed enforcers (currently only `TimestampEnforcer` is allowed extra).\n *\n * If exactly one permission type matches, its identifier is returned.\n *\n * @param args - The arguments to this function.\n * @param args.enforcers - List of enforcer contract addresses (hex strings).\n *\n * @param args.contracts - The deployed contracts for the chain.\n * @returns The identifier of the matching permission type.\n * @throws If no permission type matches, or if more than one permission type matches.\n */\nexport const identifyPermissionByEnforcers = ({\n  enforcers,\n  contracts,\n}: {\n  enforcers: Hex[];\n  contracts: DeployedContractsByName;\n}): PermissionType => {\n  const enforcersSet = new Set(enforcers.map(getChecksumAddress));\n\n  const permissionRules = createPermissionRulesForChainId(contracts);\n\n  let matchingPermissionType: PermissionType | null = null;\n\n  for (const {\n    allowedEnforcers,\n    requiredEnforcers,\n    permissionType,\n  } of permissionRules) {\n    const hasAllRequiredEnforcers = isSubset(requiredEnforcers, enforcersSet);\n\n    let hasForbiddenEnforcers = false;\n\n    for (const caveat of enforcersSet) {\n      if (!allowedEnforcers.has(caveat) && !requiredEnforcers.has(caveat)) {\n        hasForbiddenEnforcers = true;\n        break;\n      }\n    }\n\n    if (hasAllRequiredEnforcers && !hasForbiddenEnforcers) {\n      if (matchingPermissionType) {\n        throw new Error('Multiple permission types match');\n      }\n      matchingPermissionType = permissionType;\n    }\n  }\n\n  if (!matchingPermissionType) {\n    throw new Error('Unable to identify permission type');\n  }\n\n  return matchingPermissionType;\n};\n\n/**\n * Extracts the permission-specific data payload and the expiry timestamp from\n * the provided caveats for a given permission type.\n *\n * This function locates the relevant caveat enforcer for the `permissionType`,\n * interprets its `terms` by splitting the hex string into byte-sized segments,\n * and converts each segment into the appropriate numeric or address shape.\n *\n * The expiry timestamp is derived from the `TimestampEnforcer` terms and must\n * have a zero `timestampAfterThreshold` and a positive `timestampBeforeThreshold`.\n *\n * @param args - The arguments to this function.\n * @param args.contracts - The deployed contracts for the chain.\n * @param args.caveats - Caveats decoded from the permission context.\n * @param args.permissionType - The previously identified permission type.\n *\n * @returns An object containing the `expiry` timestamp and the decoded `data` payload.\n * @throws If the caveats are malformed, missing, or the terms fail to decode.\n */\nexport const getPermissionDataAndExpiry = ({\n  contracts,\n  caveats,\n  permissionType,\n}: {\n  contracts: DeployedContractsByName;\n  caveats: Caveat<Hex>[];\n  permissionType: PermissionType;\n}): {\n  expiry: number | null;\n  data: DecodedPermission['permission']['data'];\n} => {\n  const checksumCaveats = caveats.map((caveat) => ({\n    ...caveat,\n    enforcer: getChecksumAddress(caveat.enforcer),\n  }));\n\n  const {\n    erc20StreamingEnforcer,\n    erc20PeriodicEnforcer,\n    nativeTokenStreamingEnforcer,\n    nativeTokenPeriodicEnforcer,\n    timestampEnforcer,\n  } = getChecksumEnforcersByChainId(contracts);\n\n  const expiryTerms = getTermsByEnforcer({\n    caveats: checksumCaveats,\n    enforcer: timestampEnforcer,\n    throwIfNotFound: false,\n  });\n\n  let expiry: number | null = null;\n  if (expiryTerms) {\n    const [after, before] = splitHex(expiryTerms, [16, 16]);\n\n    if (hexToNumber(after) !== 0) {\n      throw new Error('Invalid expiry');\n    }\n    expiry = hexToNumber(before);\n  }\n\n  let data: DecodedPermission['permission']['data'];\n\n  switch (permissionType) {\n    case 'erc20-token-stream': {\n      const erc20StreamingTerms = getTermsByEnforcer({\n        caveats: checksumCaveats,\n        enforcer: erc20StreamingEnforcer,\n      });\n\n      const [\n        tokenAddress,\n        initialAmount,\n        maxAmount,\n        amountPerSecond,\n        startTimeRaw,\n      ] = splitHex(erc20StreamingTerms, [20, 32, 32, 32, 32]);\n\n      data = {\n        tokenAddress,\n        initialAmount,\n        maxAmount,\n        amountPerSecond,\n        startTime: hexToNumber(startTimeRaw),\n      };\n      break;\n    }\n    case 'erc20-token-periodic': {\n      const erc20PeriodicTerms = getTermsByEnforcer({\n        caveats: checksumCaveats,\n        enforcer: erc20PeriodicEnforcer,\n      });\n\n      const [tokenAddress, periodAmount, periodDurationRaw, startTimeRaw] =\n        splitHex(erc20PeriodicTerms, [20, 32, 32, 32]);\n\n      data = {\n        tokenAddress,\n        periodAmount,\n        periodDuration: hexToNumber(periodDurationRaw),\n        startTime: hexToNumber(startTimeRaw),\n      };\n      break;\n    }\n\n    case 'native-token-stream': {\n      const nativeTokenStreamingTerms = getTermsByEnforcer({\n        caveats: checksumCaveats,\n        enforcer: nativeTokenStreamingEnforcer,\n      });\n\n      const [initialAmount, maxAmount, amountPerSecond, startTimeRaw] =\n        splitHex(nativeTokenStreamingTerms, [32, 32, 32, 32]);\n\n      data = {\n        initialAmount,\n        maxAmount,\n        amountPerSecond,\n        startTime: hexToNumber(startTimeRaw),\n      };\n      break;\n    }\n    case 'native-token-periodic': {\n      const nativeTokenPeriodicTerms = getTermsByEnforcer({\n        caveats: checksumCaveats,\n        enforcer: nativeTokenPeriodicEnforcer,\n      });\n\n      const [periodAmount, periodDurationRaw, startTimeRaw] = splitHex(\n        nativeTokenPeriodicTerms,\n        [32, 32, 32],\n      );\n\n      data = {\n        periodAmount,\n        periodDuration: hexToNumber(periodDurationRaw),\n        startTime: hexToNumber(startTimeRaw),\n      };\n      break;\n    }\n    default:\n      throw new Error('Invalid permission type');\n  }\n\n  return { expiry, data };\n};\n\n/**\n * Reconstructs a {@link DecodedPermission} object from primitive values\n * obtained while decoding a permission context.\n *\n * The resulting object contains:\n * - `chainId` encoded as hex (`0x…`)\n * - `address` set to the delegator (user account)\n * - `signer` set to an account signer with the delegate address\n * - `permission` with the identified type and decoded data\n * - `expiry` timestamp (or null)\n *\n * @param args - The arguments to this function.\n * @param args.chainId - Chain ID.\n * @param args.permissionType - Identified permission type.\n * @param args.delegator - Address of the account delegating permission.\n * @param args.delegate - Address that will act under the granted permission.\n * @param args.authority - Authority identifier; must be ROOT_AUTHORITY.\n * @param args.expiry - Expiry timestamp (unix seconds) or null if unbounded.\n * @param args.data - Permission-specific decoded data payload.\n * @param args.justification - Human-readable justification for the permission.\n * @param args.specifiedOrigin - The origin reported in the request metadata.\n *\n * @returns The reconstructed {@link DecodedPermission}.\n */\nexport const reconstructDecodedPermission = ({\n  chainId,\n  permissionType,\n  delegator,\n  delegate,\n  authority,\n  expiry,\n  data,\n  justification,\n  specifiedOrigin,\n}: {\n  chainId: number;\n  permissionType: PermissionType;\n  delegator: Hex;\n  delegate: Hex;\n  authority: Hex;\n  expiry: number | null;\n  data: DecodedPermission['permission']['data'];\n  justification: string;\n  specifiedOrigin: string;\n}) => {\n  if (authority !== ROOT_AUTHORITY) {\n    throw new Error('Invalid authority');\n  }\n\n  const permission: DecodedPermission = {\n    chainId: numberToHex(chainId),\n    address: delegator,\n    signer: { type: 'account', data: { address: delegate } },\n    permission: {\n      type: permissionType,\n      data,\n      justification,\n    },\n    expiry,\n    origin: specifiedOrigin,\n  };\n\n  return permission;\n};\n"]}

package/dist/decodePermission/index.cjs

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reconstructDecodedPermission = exports.getPermissionDataAndExpiry = exports.identifyPermissionByEnforcers = void 0;
+var decodePermission_1 = require("./decodePermission.cjs");
+Object.defineProperty(exports, "identifyPermissionByEnforcers", { enumerable: true, get: function () { return decodePermission_1.identifyPermissionByEnforcers; } });
+Object.defineProperty(exports, "getPermissionDataAndExpiry", { enumerable: true, get: function () { return decodePermission_1.getPermissionDataAndExpiry; } });
+Object.defineProperty(exports, "reconstructDecodedPermission", { enumerable: true, get: function () { return decodePermission_1.reconstructDecodedPermission; } });
+//# sourceMappingURL=index.cjs.map

package/dist/decodePermission/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sourceRoot":"","sources":["../../src/decodePermission/index.ts"],"names":[],"mappings":";;;AAAA,2DAI4B;AAH1B,iIAAA,6BAA6B,OAAA;AAC7B,8HAAA,0BAA0B,OAAA;AAC1B,gIAAA,4BAA4B,OAAA","sourcesContent":["export {\n  identifyPermissionByEnforcers,\n  getPermissionDataAndExpiry,\n  reconstructDecodedPermission,\n} from './decodePermission';\n\nexport type { DecodedPermission } from './types';\n"]}

package/dist/decodePermission/index.d.cts

@@ -0,0 +1,3 @@
+export { identifyPermissionByEnforcers, getPermissionDataAndExpiry, reconstructDecodedPermission, } from "./decodePermission.cjs";
+export type { DecodedPermission } from "./types.cjs";
+//# sourceMappingURL=index.d.cts.map

package/dist/decodePermission/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../../src/decodePermission/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,4BAA4B,GAC7B,+BAA2B;AAE5B,YAAY,EAAE,iBAAiB,EAAE,oBAAgB"}

package/dist/decodePermission/index.d.mts

@@ -0,0 +1,3 @@
+export { identifyPermissionByEnforcers, getPermissionDataAndExpiry, reconstructDecodedPermission, } from "./decodePermission.mjs";
+export type { DecodedPermission } from "./types.mjs";
+//# sourceMappingURL=index.d.mts.map

package/dist/decodePermission/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/decodePermission/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,4BAA4B,GAC7B,+BAA2B;AAE5B,YAAY,EAAE,iBAAiB,EAAE,oBAAgB"}

package/dist/decodePermission/index.mjs

@@ -0,0 +1,2 @@
+export { identifyPermissionByEnforcers, getPermissionDataAndExpiry, reconstructDecodedPermission } from "./decodePermission.mjs";
+//# sourceMappingURL=index.mjs.map

package/dist/decodePermission/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../src/decodePermission/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,6BAA6B,EAC7B,0BAA0B,EAC1B,4BAA4B,EAC7B,+BAA2B","sourcesContent":["export {\n  identifyPermissionByEnforcers,\n  getPermissionDataAndExpiry,\n  reconstructDecodedPermission,\n} from './decodePermission';\n\nexport type { DecodedPermission } from './types';\n"]}

package/dist/decodePermission/types.cjs

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.cjs.map

package/dist/decodePermission/types.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.cjs","sourceRoot":"","sources":["../../src/decodePermission/types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  PermissionRequest,\n  PermissionTypes,\n  Signer,\n} from '@metamask/7715-permission-types';\nimport type { DELEGATOR_CONTRACTS } from '@metamask/delegation-deployments';\n\nexport type DeployedContractsByName =\n  (typeof DELEGATOR_CONTRACTS)[number][number];\n\n// This is a somewhat convoluted type - it includes all of the fields that are decoded from the permission context.\n/**\n * A partially reconstructed permission object decoded from a permission context.\n *\n * This mirrors the shape of {@link PermissionRequest} for fields that can be\n * deterministically recovered from the encoded permission context, and it\n * augments the result with an explicit `expiry` property derived from the\n * `TimestampEnforcer` terms, as well as the `origin` property.\n */\nexport type DecodedPermission = Pick<\n  PermissionRequest<Signer, PermissionTypes>,\n  'chainId' | 'address' | 'signer'\n> & {\n  permission: Omit<\n    PermissionRequest<Signer, PermissionTypes>['permission'],\n    'isAdjustmentAllowed'\n  > & {\n    // PermissionRequest type does not work well without the specific permission type, so we amend it here\n    justification?: string;\n  };\n  expiry: number | null;\n  origin: string;\n};\n\n/**\n * Supported permission type identifiers that can be decoded from a permission context.\n */\nexport type PermissionType = DecodedPermission['permission']['type'];\n"]}

package/dist/decodePermission/types.d.cts

@@ -0,0 +1,23 @@
+import type { PermissionRequest, PermissionTypes, Signer } from "@metamask/7715-permission-types";
+import type { DELEGATOR_CONTRACTS } from "@metamask/delegation-deployments";
+export type DeployedContractsByName = (typeof DELEGATOR_CONTRACTS)[number][number];
+/**
+ * A partially reconstructed permission object decoded from a permission context.
+ *
+ * This mirrors the shape of {@link PermissionRequest} for fields that can be
+ * deterministically recovered from the encoded permission context, and it
+ * augments the result with an explicit `expiry` property derived from the
+ * `TimestampEnforcer` terms, as well as the `origin` property.
+ */
+export type DecodedPermission = Pick<PermissionRequest<Signer, PermissionTypes>, 'chainId' | 'address' | 'signer'> & {
+    permission: Omit<PermissionRequest<Signer, PermissionTypes>['permission'], 'isAdjustmentAllowed'> & {
+        justification?: string;
+    };
+    expiry: number | null;
+    origin: string;
+};
+/**
+ * Supported permission type identifiers that can be decoded from a permission context.
+ */
+export type PermissionType = DecodedPermission['permission']['type'];
+//# sourceMappingURL=types.d.cts.map

package/dist/decodePermission/types.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.cts","sourceRoot":"","sources":["../../src/decodePermission/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,MAAM,EACP,wCAAwC;AACzC,OAAO,KAAK,EAAE,mBAAmB,EAAE,yCAAyC;AAE5E,MAAM,MAAM,uBAAuB,GACjC,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAG/C;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,iBAAiB,CAAC,MAAM,EAAE,eAAe,CAAC,EAC1C,SAAS,GAAG,SAAS,GAAG,QAAQ,CACjC,GAAG;IACF,UAAU,EAAE,IAAI,CACd,iBAAiB,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,YAAY,CAAC,EACxD,qBAAqB,CACtB,GAAG;QAEF,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/decodePermission/types.d.mts

@@ -0,0 +1,23 @@
+import type { PermissionRequest, PermissionTypes, Signer } from "@metamask/7715-permission-types";
+import type { DELEGATOR_CONTRACTS } from "@metamask/delegation-deployments";
+export type DeployedContractsByName = (typeof DELEGATOR_CONTRACTS)[number][number];
+/**
+ * A partially reconstructed permission object decoded from a permission context.
+ *
+ * This mirrors the shape of {@link PermissionRequest} for fields that can be
+ * deterministically recovered from the encoded permission context, and it
+ * augments the result with an explicit `expiry` property derived from the
+ * `TimestampEnforcer` terms, as well as the `origin` property.
+ */
+export type DecodedPermission = Pick<PermissionRequest<Signer, PermissionTypes>, 'chainId' | 'address' | 'signer'> & {
+    permission: Omit<PermissionRequest<Signer, PermissionTypes>['permission'], 'isAdjustmentAllowed'> & {
+        justification?: string;
+    };
+    expiry: number | null;
+    origin: string;
+};
+/**
+ * Supported permission type identifiers that can be decoded from a permission context.
+ */
+export type PermissionType = DecodedPermission['permission']['type'];
+//# sourceMappingURL=types.d.mts.map

package/dist/decodePermission/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../../src/decodePermission/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,MAAM,EACP,wCAAwC;AACzC,OAAO,KAAK,EAAE,mBAAmB,EAAE,yCAAyC;AAE5E,MAAM,MAAM,uBAAuB,GACjC,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC;AAG/C;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,iBAAiB,CAAC,MAAM,EAAE,eAAe,CAAC,EAC1C,SAAS,GAAG,SAAS,GAAG,QAAQ,CACjC,GAAG;IACF,UAAU,EAAE,IAAI,CACd,iBAAiB,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,YAAY,CAAC,EACxD,qBAAqB,CACtB,GAAG;QAEF,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,iBAAiB,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/decodePermission/types.mjs

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.mjs.map

package/dist/decodePermission/types.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.mjs","sourceRoot":"","sources":["../../src/decodePermission/types.ts"],"names":[],"mappings":"","sourcesContent":["import type {\n  PermissionRequest,\n  PermissionTypes,\n  Signer,\n} from '@metamask/7715-permission-types';\nimport type { DELEGATOR_CONTRACTS } from '@metamask/delegation-deployments';\n\nexport type DeployedContractsByName =\n  (typeof DELEGATOR_CONTRACTS)[number][number];\n\n// This is a somewhat convoluted type - it includes all of the fields that are decoded from the permission context.\n/**\n * A partially reconstructed permission object decoded from a permission context.\n *\n * This mirrors the shape of {@link PermissionRequest} for fields that can be\n * deterministically recovered from the encoded permission context, and it\n * augments the result with an explicit `expiry` property derived from the\n * `TimestampEnforcer` terms, as well as the `origin` property.\n */\nexport type DecodedPermission = Pick<\n  PermissionRequest<Signer, PermissionTypes>,\n  'chainId' | 'address' | 'signer'\n> & {\n  permission: Omit<\n    PermissionRequest<Signer, PermissionTypes>['permission'],\n    'isAdjustmentAllowed'\n  > & {\n    // PermissionRequest type does not work well without the specific permission type, so we amend it here\n    justification?: string;\n  };\n  expiry: number | null;\n  origin: string;\n};\n\n/**\n * Supported permission type identifiers that can be decoded from a permission context.\n */\nexport type PermissionType = DecodedPermission['permission']['type'];\n"]}

package/dist/decodePermission/utils.cjs

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitHex = exports.getTermsByEnforcer = exports.isSubset = exports.createPermissionRulesForChainId = exports.getChecksumEnforcersByChainId = void 0;
+const utils_1 = require("@metamask/utils");
+/**
+ * The names of the enforcer contracts for each permission type.
+ */
+const ENFORCER_CONTRACT_NAMES = {
+    ERC20PeriodTransferEnforcer: 'ERC20PeriodTransferEnforcer',
+    ERC20StreamingEnforcer: 'ERC20StreamingEnforcer',
+    ExactCalldataEnforcer: 'ExactCalldataEnforcer',
+    NativeTokenPeriodTransferEnforcer: 'NativeTokenPeriodTransferEnforcer',
+    NativeTokenStreamingEnforcer: 'NativeTokenStreamingEnforcer',
+    TimestampEnforcer: 'TimestampEnforcer',
+    ValueLteEnforcer: 'ValueLteEnforcer',
+    NonceEnforcer: 'NonceEnforcer',
+};
+/**
+ * Resolves and returns checksummed addresses of all known enforcer contracts
+ * for a given `chainId` under the current delegation framework version.
+ *
+ * @param contracts - The deployed contracts for the chain.
+ * @returns An object mapping enforcer names to checksummed contract addresses.
+ * @throws If the chain or an expected enforcer contract is not found.
+ */
+const getChecksumEnforcersByChainId = (contracts) => {
+    const getChecksumContractAddress = (contractName) => {
+        const address = contracts[contractName];
+        if (!address) {
+            throw new Error(`Contract not found: ${contractName}`);
+        }
+        return (0, utils_1.getChecksumAddress)(address);
+    };
+    // permission type specific enforcers
+    const erc20StreamingEnforcer = getChecksumContractAddress(ENFORCER_CONTRACT_NAMES.ERC20StreamingEnforcer);
+    const erc20PeriodicEnforcer = getChecksumContractAddress(ENFORCER_CONTRACT_NAMES.ERC20PeriodTransferEnforcer);
+    const nativeTokenStreamingEnforcer = getChecksumContractAddress(ENFORCER_CONTRACT_NAMES.NativeTokenStreamingEnforcer);
+    const nativeTokenPeriodicEnforcer = getChecksumContractAddress(ENFORCER_CONTRACT_NAMES.NativeTokenPeriodTransferEnforcer);
+    // general enforcers
+    const exactCalldataEnforcer = getChecksumContractAddress(ENFORCER_CONTRACT_NAMES.ExactCalldataEnforcer);
+    const valueLteEnforcer = getChecksumContractAddress(ENFORCER_CONTRACT_NAMES.ValueLteEnforcer);
+    const timestampEnforcer = getChecksumContractAddress(ENFORCER_CONTRACT_NAMES.TimestampEnforcer);
+    const nonceEnforcer = getChecksumContractAddress(ENFORCER_CONTRACT_NAMES.NonceEnforcer);
+    return {
+        erc20StreamingEnforcer,
+        erc20PeriodicEnforcer,
+        nativeTokenStreamingEnforcer,
+        nativeTokenPeriodicEnforcer,
+        exactCalldataEnforcer,
+        valueLteEnforcer,
+        timestampEnforcer,
+        nonceEnforcer,
+    };
+};
+exports.getChecksumEnforcersByChainId = getChecksumEnforcersByChainId;
+/**
+ * Builds the canonical set of permission matching rules for a chain.
+ *
+ * Each rule specifies the `permissionType`, the set of `requiredEnforcers`
+ * that must be present, and the set of `allowedEnforcers` that may appear in
+ * addition to the required set.
+ *
+ * @param contracts - The deployed contracts for the chain.
+ * @returns A list of permission rules used to identify permission types.
+ * @throws Propagates any errors from resolving enforcer addresses.
+ */
+const createPermissionRulesForChainId = (contracts) => {
+    const { erc20StreamingEnforcer, erc20PeriodicEnforcer, nativeTokenStreamingEnforcer, nativeTokenPeriodicEnforcer, exactCalldataEnforcer, valueLteEnforcer, timestampEnforcer, nonceEnforcer, } = (0, exports.getChecksumEnforcersByChainId)(contracts);
+    // the allowed enforcers are the same for all permission types
+    const allowedEnforcers = new Set([timestampEnforcer]);
+    const permissionRules = [
+        {
+            requiredEnforcers: new Set([
+                nativeTokenStreamingEnforcer,
+                exactCalldataEnforcer,
+                nonceEnforcer,
+            ]),
+            allowedEnforcers,
+            permissionType: 'native-token-stream',
+        },
+        {
+            requiredEnforcers: new Set([
+                nativeTokenPeriodicEnforcer,
+                exactCalldataEnforcer,
+                nonceEnforcer,
+            ]),
+            allowedEnforcers,
+            permissionType: 'native-token-periodic',
+        },
+        {
+            requiredEnforcers: new Set([
+                erc20StreamingEnforcer,
+                valueLteEnforcer,
+                nonceEnforcer,
+            ]),
+            allowedEnforcers,
+            permissionType: 'erc20-token-stream',
+        },
+        {
+            requiredEnforcers: new Set([
+                erc20PeriodicEnforcer,
+                valueLteEnforcer,
+                nonceEnforcer,
+            ]),
+            allowedEnforcers,
+            permissionType: 'erc20-token-periodic',
+        },
+    ];
+    return permissionRules;
+};
+exports.createPermissionRulesForChainId = createPermissionRulesForChainId;
+/**
+ * Determines whether all elements of `subset` are contained within `superset`.
+ *
+ * @param subset - The candidate subset to test.
+ * @param superset - The set expected to contain all elements of `subset`.
+ * @returns `true` if `subset` ⊆ `superset`, otherwise `false`.
+ */
+const isSubset = (subset, superset) => {
+    for (const x of subset) {
+        if (!superset.has(x)) {
+            return false;
+        }
+    }
+    return true;
+};
+exports.isSubset = isSubset;
+/**
+ * Gets the terms for a given enforcer from a list of caveats.
+ *
+ * @param args - The arguments to this function.
+ * @param  args.throwIfNotFound - Whether to throw an error if no matching enforcer is found. Default is true.
+ * @param args.caveats - The list of caveats to search.
+ * @param args.enforcer - The enforcer to search for.
+ * @returns The terms for the given enforcer.
+ */
+function getTermsByEnforcer({ caveats, enforcer, throwIfNotFound, }) {
+    const matchingCaveats = caveats.filter((caveat) => caveat.enforcer === enforcer);
+    if (matchingCaveats.length === 0) {
+        if (throwIfNotFound ?? true) {
+            throw new Error('Invalid caveats');
+        }
+        return null;
+    }
+    if (matchingCaveats.length > 1) {
+        throw new Error('Invalid caveats');
+    }
+    return matchingCaveats[0].terms;
+}
+exports.getTermsByEnforcer = getTermsByEnforcer;
+/**
+ * Splits a 0x-prefixed hex string into parts according to the provided byte lengths.
+ *
+ * Each entry in `lengths` represents a part length in bytes; internally this is
+ * multiplied by 2 to derive the number of hexadecimal characters to slice. The
+ * returned substrings do not include the `0x` prefix and preserve leading zeros.
+ *
+ * Note: This function does not perform input validation (e.g., verifying the
+ * payload length equals the sum of requested lengths). Callers are expected to
+ * provide well-formed inputs.
+ *
+ * Example:
+ * splitHex('0x12345678', [1, 3]) => ['0x12', '0x345678']
+ *
+ * @param value - The 0x-prefixed hex string to split.
+ * @param lengths - The lengths of each part, in bytes.
+ * @returns An array of hex substrings (each with `0x` prefix), one for each part.
+ */
+function splitHex(value, lengths) {
+    let start = 2;
+    const parts = [];
+    for (const partLength of lengths) {
+        const partCharLength = partLength * 2;
+        const part = value.slice(start, start + partCharLength);
+        start += partCharLength;
+        parts.push(`0x${part}`);
+    }
+    return parts;
+}
+exports.splitHex = splitHex;
+//# sourceMappingURL=utils.cjs.map

package/dist/decodePermission/utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.cjs","sourceRoot":"","sources":["../../src/decodePermission/utils.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Caveat } from '@metamask/delegation-core';\nimport { getChecksumAddress, type Hex } from '@metamask/utils';\n\nimport type { DeployedContractsByName, PermissionType } from './types';\n\n/**\n * A rule that defines the required and allowed enforcers for a permission type.\n */\nexport type PermissionRule = {\n  permissionType: PermissionType;\n  requiredEnforcers: Set<Hex>;\n  allowedEnforcers: Set<Hex>;\n};\n\n/**\n * The names of the enforcer contracts for each permission type.\n */\nconst ENFORCER_CONTRACT_NAMES = {\n  ERC20PeriodTransferEnforcer: 'ERC20PeriodTransferEnforcer',\n  ERC20StreamingEnforcer: 'ERC20StreamingEnforcer',\n  ExactCalldataEnforcer: 'ExactCalldataEnforcer',\n  NativeTokenPeriodTransferEnforcer: 'NativeTokenPeriodTransferEnforcer',\n  NativeTokenStreamingEnforcer: 'NativeTokenStreamingEnforcer',\n  TimestampEnforcer: 'TimestampEnforcer',\n  ValueLteEnforcer: 'ValueLteEnforcer',\n  NonceEnforcer: 'NonceEnforcer',\n};\n\n/**\n * Resolves and returns checksummed addresses of all known enforcer contracts\n * for a given `chainId` under the current delegation framework version.\n *\n * @param contracts - The deployed contracts for the chain.\n * @returns An object mapping enforcer names to checksummed contract addresses.\n * @throws If the chain or an expected enforcer contract is not found.\n */\nexport const getChecksumEnforcersByChainId = (\n  contracts: DeployedContractsByName,\n) => {\n  const getChecksumContractAddress = (contractName: string) => {\n    const address = contracts[contractName];\n\n    if (!address) {\n      throw new Error(`Contract not found: ${contractName}`);\n    }\n\n    return getChecksumAddress(address);\n  };\n\n  // permission type specific enforcers\n  const erc20StreamingEnforcer = getChecksumContractAddress(\n    ENFORCER_CONTRACT_NAMES.ERC20StreamingEnforcer,\n  );\n  const erc20PeriodicEnforcer = getChecksumContractAddress(\n    ENFORCER_CONTRACT_NAMES.ERC20PeriodTransferEnforcer,\n  );\n  const nativeTokenStreamingEnforcer = getChecksumContractAddress(\n    ENFORCER_CONTRACT_NAMES.NativeTokenStreamingEnforcer,\n  );\n  const nativeTokenPeriodicEnforcer = getChecksumContractAddress(\n    ENFORCER_CONTRACT_NAMES.NativeTokenPeriodTransferEnforcer,\n  );\n\n  // general enforcers\n  const exactCalldataEnforcer = getChecksumContractAddress(\n    ENFORCER_CONTRACT_NAMES.ExactCalldataEnforcer,\n  );\n  const valueLteEnforcer = getChecksumContractAddress(\n    ENFORCER_CONTRACT_NAMES.ValueLteEnforcer,\n  );\n  const timestampEnforcer = getChecksumContractAddress(\n    ENFORCER_CONTRACT_NAMES.TimestampEnforcer,\n  );\n  const nonceEnforcer = getChecksumContractAddress(\n    ENFORCER_CONTRACT_NAMES.NonceEnforcer,\n  );\n\n  return {\n    erc20StreamingEnforcer,\n    erc20PeriodicEnforcer,\n    nativeTokenStreamingEnforcer,\n    nativeTokenPeriodicEnforcer,\n    exactCalldataEnforcer,\n    valueLteEnforcer,\n    timestampEnforcer,\n    nonceEnforcer,\n  };\n};\n\n/**\n * Builds the canonical set of permission matching rules for a chain.\n *\n * Each rule specifies the `permissionType`, the set of `requiredEnforcers`\n * that must be present, and the set of `allowedEnforcers` that may appear in\n * addition to the required set.\n *\n * @param contracts - The deployed contracts for the chain.\n * @returns A list of permission rules used to identify permission types.\n * @throws Propagates any errors from resolving enforcer addresses.\n */\nexport const createPermissionRulesForChainId: (\n  contracts: DeployedContractsByName,\n) => PermissionRule[] = (contracts: DeployedContractsByName) => {\n  const {\n    erc20StreamingEnforcer,\n    erc20PeriodicEnforcer,\n    nativeTokenStreamingEnforcer,\n    nativeTokenPeriodicEnforcer,\n    exactCalldataEnforcer,\n    valueLteEnforcer,\n    timestampEnforcer,\n    nonceEnforcer,\n  } = getChecksumEnforcersByChainId(contracts);\n\n  // the allowed enforcers are the same for all permission types\n  const allowedEnforcers = new Set<Hex>([timestampEnforcer]);\n\n  const permissionRules: PermissionRule[] = [\n    {\n      requiredEnforcers: new Set<Hex>([\n        nativeTokenStreamingEnforcer,\n        exactCalldataEnforcer,\n        nonceEnforcer,\n      ]),\n      allowedEnforcers,\n      permissionType: 'native-token-stream',\n    },\n    {\n      requiredEnforcers: new Set<Hex>([\n        nativeTokenPeriodicEnforcer,\n        exactCalldataEnforcer,\n        nonceEnforcer,\n      ]),\n      allowedEnforcers,\n      permissionType: 'native-token-periodic',\n    },\n    {\n      requiredEnforcers: new Set<Hex>([\n        erc20StreamingEnforcer,\n        valueLteEnforcer,\n        nonceEnforcer,\n      ]),\n      allowedEnforcers,\n      permissionType: 'erc20-token-stream',\n    },\n    {\n      requiredEnforcers: new Set<Hex>([\n        erc20PeriodicEnforcer,\n        valueLteEnforcer,\n        nonceEnforcer,\n      ]),\n      allowedEnforcers,\n      permissionType: 'erc20-token-periodic',\n    },\n  ];\n\n  return permissionRules;\n};\n\n/**\n * Determines whether all elements of `subset` are contained within `superset`.\n *\n * @param subset - The candidate subset to test.\n * @param superset - The set expected to contain all elements of `subset`.\n * @returns `true` if `subset` ⊆ `superset`, otherwise `false`.\n */\nexport const isSubset = <T>(subset: Set<T>, superset: Set<T>): boolean => {\n  for (const x of subset) {\n    if (!superset.has(x)) {\n      return false;\n    }\n  }\n  return true;\n};\n\n/**\n * Gets the terms for a given enforcer from a list of caveats.\n *\n * @param args - The arguments to this function.\n * @param  args.throwIfNotFound - Whether to throw an error if no matching enforcer is found. Default is true.\n * @param args.caveats - The list of caveats to search.\n * @param args.enforcer - The enforcer to search for.\n * @returns The terms for the given enforcer.\n */\nexport function getTermsByEnforcer<TThrowIfNotFound extends boolean = true>({\n  caveats,\n  enforcer,\n  throwIfNotFound,\n}: {\n  caveats: Caveat<Hex>[];\n  enforcer: Hex;\n  throwIfNotFound?: TThrowIfNotFound;\n}): TThrowIfNotFound extends true ? Hex : Hex | null {\n  const matchingCaveats = caveats.filter(\n    (caveat) => caveat.enforcer === enforcer,\n  );\n\n  if (matchingCaveats.length === 0) {\n    if (throwIfNotFound ?? true) {\n      throw new Error('Invalid caveats');\n    }\n    return null as TThrowIfNotFound extends true ? Hex : Hex | null;\n  }\n\n  if (matchingCaveats.length > 1) {\n    throw new Error('Invalid caveats');\n  }\n\n  return matchingCaveats[0].terms;\n}\n\n/**\n * Splits a 0x-prefixed hex string into parts according to the provided byte lengths.\n *\n * Each entry in `lengths` represents a part length in bytes; internally this is\n * multiplied by 2 to derive the number of hexadecimal characters to slice. The\n * returned substrings do not include the `0x` prefix and preserve leading zeros.\n *\n * Note: This function does not perform input validation (e.g., verifying the\n * payload length equals the sum of requested lengths). Callers are expected to\n * provide well-formed inputs.\n *\n * Example:\n * splitHex('0x12345678', [1, 3]) => ['0x12', '0x345678']\n *\n * @param value - The 0x-prefixed hex string to split.\n * @param lengths - The lengths of each part, in bytes.\n * @returns An array of hex substrings (each with `0x` prefix), one for each part.\n */\nexport function splitHex(value: Hex, lengths: number[]): Hex[] {\n  let start = 2;\n  const parts: Hex[] = [];\n  for (const partLength of lengths) {\n    const partCharLength = partLength * 2;\n    const part = value.slice(start, start + partCharLength);\n    start += partCharLength;\n    parts.push(`0x${part}` as Hex);\n  }\n  return parts;\n}\n"]}

package/dist/decodePermission/utils.d.cts

@@ -0,0 +1,83 @@
+import type { Caveat } from "@metamask/delegation-core";
+import { type Hex } from "@metamask/utils";
+import type { DeployedContractsByName, PermissionType } from "./types.cjs";
+/**
+ * A rule that defines the required and allowed enforcers for a permission type.
+ */
+export type PermissionRule = {
+    permissionType: PermissionType;
+    requiredEnforcers: Set<Hex>;
+    allowedEnforcers: Set<Hex>;
+};
+/**
+ * Resolves and returns checksummed addresses of all known enforcer contracts
+ * for a given `chainId` under the current delegation framework version.
+ *
+ * @param contracts - The deployed contracts for the chain.
+ * @returns An object mapping enforcer names to checksummed contract addresses.
+ * @throws If the chain or an expected enforcer contract is not found.
+ */
+export declare const getChecksumEnforcersByChainId: (contracts: DeployedContractsByName) => {
+    erc20StreamingEnforcer: `0x${string}`;
+    erc20PeriodicEnforcer: `0x${string}`;
+    nativeTokenStreamingEnforcer: `0x${string}`;
+    nativeTokenPeriodicEnforcer: `0x${string}`;
+    exactCalldataEnforcer: `0x${string}`;
+    valueLteEnforcer: `0x${string}`;
+    timestampEnforcer: `0x${string}`;
+    nonceEnforcer: `0x${string}`;
+};
+/**
+ * Builds the canonical set of permission matching rules for a chain.
+ *
+ * Each rule specifies the `permissionType`, the set of `requiredEnforcers`
+ * that must be present, and the set of `allowedEnforcers` that may appear in
+ * addition to the required set.
+ *
+ * @param contracts - The deployed contracts for the chain.
+ * @returns A list of permission rules used to identify permission types.
+ * @throws Propagates any errors from resolving enforcer addresses.
+ */
+export declare const createPermissionRulesForChainId: (contracts: DeployedContractsByName) => PermissionRule[];
+/**
+ * Determines whether all elements of `subset` are contained within `superset`.
+ *
+ * @param subset - The candidate subset to test.
+ * @param superset - The set expected to contain all elements of `subset`.
+ * @returns `true` if `subset` ⊆ `superset`, otherwise `false`.
+ */
+export declare const isSubset: <T>(subset: Set<T>, superset: Set<T>) => boolean;
+/**
+ * Gets the terms for a given enforcer from a list of caveats.
+ *
+ * @param args - The arguments to this function.
+ * @param  args.throwIfNotFound - Whether to throw an error if no matching enforcer is found. Default is true.
+ * @param args.caveats - The list of caveats to search.
+ * @param args.enforcer - The enforcer to search for.
+ * @returns The terms for the given enforcer.
+ */
+export declare function getTermsByEnforcer<TThrowIfNotFound extends boolean = true>({ caveats, enforcer, throwIfNotFound, }: {
+    caveats: Caveat<Hex>[];
+    enforcer: Hex;
+    throwIfNotFound?: TThrowIfNotFound;
+}): TThrowIfNotFound extends true ? Hex : Hex | null;
+/**
+ * Splits a 0x-prefixed hex string into parts according to the provided byte lengths.
+ *
+ * Each entry in `lengths` represents a part length in bytes; internally this is
+ * multiplied by 2 to derive the number of hexadecimal characters to slice. The
+ * returned substrings do not include the `0x` prefix and preserve leading zeros.
+ *
+ * Note: This function does not perform input validation (e.g., verifying the
+ * payload length equals the sum of requested lengths). Callers are expected to
+ * provide well-formed inputs.
+ *
+ * Example:
+ * splitHex('0x12345678', [1, 3]) => ['0x12', '0x345678']
+ *
+ * @param value - The 0x-prefixed hex string to split.
+ * @param lengths - The lengths of each part, in bytes.
+ * @returns An array of hex substrings (each with `0x` prefix), one for each part.
+ */
+export declare function splitHex(value: Hex, lengths: number[]): Hex[];
+//# sourceMappingURL=utils.d.cts.map

package/dist/decodePermission/utils.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.cts","sourceRoot":"","sources":["../../src/decodePermission/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,kCAAkC;AACxD,OAAO,EAAsB,KAAK,GAAG,EAAE,wBAAwB;AAE/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,cAAc,EAAE,oBAAgB;AAEvE;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,cAAc,EAAE,cAAc,CAAC;IAC/B,iBAAiB,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,gBAAgB,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;CAC5B,CAAC;AAgBF;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,cAC7B,uBAAuB;;;;;;;;;CAkDnC,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,+BAA+B,EAAE,CAC5C,SAAS,EAAE,uBAAuB,KAC/B,cAAc,EAuDlB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,2CAA0C,OAO9D,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,gBAAgB,SAAS,OAAO,GAAG,IAAI,EAAE,EAC1E,OAAO,EACP,QAAQ,EACR,eAAe,GAChB,EAAE;IACD,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;IACvB,QAAQ,EAAE,GAAG,CAAC;IACd,eAAe,CAAC,EAAE,gBAAgB,CAAC;CACpC,GAAG,gBAAgB,SAAS,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,IAAI,CAiBnD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,EAAE,CAU7D"}