@debridge-finance/borderless-validation-sdk 0.0.0-dev-dee2389 → 0.0.0-dev-25d2153

package/README.md

@@ -0,0 +1,164 @@
+# @debridge-finance/borderless-validation-sdk
+
+Validation SDK for deBridge **borderless intents** API (`POST /v1.0/bundle`) responses.
+
+## Purpose
+
+When a user submits a bundle request to the deBridge API, the response contains transactions and signable payloads (EIP-712 messages, permits, Solana transactions, etc.) that the user is expected to sign.
+
+**Every field the user signs is a potential attack vector.** If the API is compromised (MITM, server bug, malicious rewrite), the user could unknowingly sign a transaction that drains their funds.
+
+This SDK runs on the client and independently verifies that every signable field in the response matches the original request — before the user signs anything.
+
+### Threats mitigated
+
+- **MITM attacks** against the API endpoint.
+- **Bugs on the API side** that produce subtly wrong responses.
+- **Reduced API trust** — the client no longer has to take API responses on faith.
+- **Regression safety net** when testing new API versions.
+
+## Installation
+
+```bash
+npm install @debridge-finance/borderless-validation-sdk
+```
+
+Peer dependencies:
+
+```bash
+npm install viem zod bs58 @solana/web3.js
+```
+
+## Basic usage
+
+```ts
+import { createValidator, Environment } from "@debridge-finance/borderless-validation-sdk";
+
+const validator = createValidator({ environment: Environment.Prod });
+
+const url = "https://cross-chain-api.debridge.finance/v1.0/bundle";
+
+const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(request),
+}).then(res => res.json());
+
+const result = validator.validate(url, request, response);
+
+if (!result.ok) {
+    console.error("Validation failed:", result.violations);
+    // Do NOT let the user sign anything.
+    return;
+}
+
+// Safe to proceed with signing.
+```
+
+### API
+
+```ts
+createValidator(config: { environment: Environment }): Validator
+
+type Validator = {
+    validate(url: string, request: object, response: object): ValidationResult;
+};
+
+type ValidationResult = {
+    ok: boolean;             // true if no violations
+    violations: Violation[]; // all issues found
+};
+
+type Violation = {
+    code: ViolationCode;     // machine-readable identifier
+    message: string;         // human-readable description
+    path: string;            // JSON path of the offending field
+    expected?: unknown;
+    actual?: unknown;
+    details?: unknown;
+};
+```
+
+`validator.validate()` **never throws** — every error condition is reported as a `Violation`. Safe to call in any code path.
+
+## Integration guide for UI teams
+
+The SDK is designed to run **between** receiving the API response and presenting it to the user for signing. Wire it into that seam.
+
+### 1. Where to call
+
+```
+┌──────────────┐     ┌─────────┐     ┌─────────────────-─┐     ┌──────────────┐
+│ Build request│ ──▶ │ fetch() │ ──▶ │ validator.validate│ ──▶ │ Sign / submit│
+└──────────────┘     └─────────┘     └──────────────────-┘     └──────────────┘
+                                              │
+                                              ▼
+                                     ok ? proceed : block
+```
+
+- **Before `validate`:** the user has not yet seen or signed anything.
+- **After `validate`:** if `result.ok === false`, **do not forward any signable payload** (intent message, permit, transaction) to the wallet. The API response cannot be trusted.
+
+### 2. Choosing the environment
+
+```ts
+import { Environment } from "@debridge-finance/borderless-validation-sdk";
+```
+
+- `Environment.Prod` — production.
+- `Environment.Hanoi`, `Environment.Dubai`, `Environment.Madrid` — non-prod deployments (may have empty whitelists; ask the SDK team before use).
+
+Pass the same environment your app is already configured for — don't make it user-selectable.
+
+### 3. Pass the exact URL you called
+
+```ts
+const url = "https://cross-chain-api.debridge.finance/v1.0/bundle";
+const response = await fetch(url, { ... });
+const result = validator.validate(url, request, response);
+```
+
+The `url` argument is checked against a per-environment whitelist. Passing a hardcoded constant defeats the check — pass the same string you handed to `fetch`.
+
+### 4. Handling violations
+
+On `result.ok === false`:
+
+1. **Block the signing flow.** Do not show a wallet popup or write any pending tx to state.
+2. **Log the full `violations` array** to your error reporting system (Sentry / Datadog / etc.). Include `code`, `path`, `expected`, `actual`, `details`.
+3. **Show the user a generic error.** Do not leak raw `Violation` data into the UI — messages are for developers, not end-users. A single "Quote is invalid, please retry" is enough.
+4. **Do not retry automatically.** If the API is compromised, retries make it worse. Let the user manually trigger a retry.
+
+### 5. Browser compatibility
+
+The SDK is published as both CJS and ESM and uses only browser-compatible APIs (no `fs`, `crypto`, `Buffer`, `process`). It has been smoke-tested in a plain `<script type="module">` environment — see [`tmp/front/`](./tmp/front/) for a minimal example.
+
+Tree-shaking: the ESM build preserves named exports. Importing only `createValidator` will not pull in unused validators.
+
+### 6. Bundle size
+
+Roughly 1 MB unpacked (a lot of it is source maps — drop them in production). The heaviest peer dep is `@solana/web3.js`; if your app only deals with EVM trades, your bundler's tree-shaking should eliminate most of it.
+
+### 7. TypeScript
+
+Full type declarations ship in `dist/types/`. `ValidatorConfig`, `ValidationResult`, `Violation`, and `ViolationCode` are all exported — use them directly, don't re-declare.
+
+### 8. What NOT to do
+
+- ❌ **Don't skip validation** because "the API is our own." Compromise detection is the whole point.
+- ❌ **Don't mutate `request` or `response`** between the API call and `validate()` — the validator needs the exact payload the user received.
+- ❌ **Don't interpret `violations[].message` programmatically** — message wording may change between versions. Branch on `code` instead.
+- ❌ **Don't cache the validator if `environment` changes.** Create a new instance via `createValidator` for each environment.
+
+## Development
+
+See [`CLAUDE.md`](./CLAUDE.md) for project conventions, validation rules, and security guidelines.
+
+- Unit tests: `npm test`
+- Coverage: `npm run coverage`
+- E2E tests (hit the staging API): `npm run test:e2e`
+- Build: `npm run build`
+
+## License
+
+BUSL-1.1

package/dist/cjs/helpers/address.js

@@ -3,11 +3,13 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AddressFormat = exports.TRON_NATIVE_ADDRESS = void 0;
-exports.getAddressFormat = getAddressFormat;
+exports.TRON_NATIVE_ADDRESS = void 0;
+exports.getChainEngine = getChainEngine;
 exports.isTronAddress = isTronAddress;
 exports.tronAddressToEvmHex = tronAddressToEvmHex;
 exports.normalizeAddress = normalizeAddress;
+exports.detectChainEngine = detectChainEngine;
+exports.normalizeAddressByValue = normalizeAddressByValue;
 exports.addressEquals = addressEquals;
 exports.isNativeToken = isNativeToken;
 const viem_1 = require("viem");
@@ -16,18 +18,12 @@ const enums_1 = require("../types/enums");
 const solana_1 = require("../whitelists/solana");
 // Tron-specific addresses (Base58Check format)
 exports.TRON_NATIVE_ADDRESS = "T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb";
-var AddressFormat;
-(function (AddressFormat) {
-    AddressFormat[AddressFormat["EVM"] = 0] = "EVM";
-    AddressFormat[AddressFormat["Tron"] = 1] = "Tron";
-    AddressFormat[AddressFormat["Solana"] = 2] = "Solana";
-})(AddressFormat || (exports.AddressFormat = AddressFormat = {}));
-function getAddressFormat(chainId) {
+function getChainEngine(chainId) {
     if (chainId === enums_1.ChainId.Tron)
-        return AddressFormat.Tron;
+        return enums_1.ChainEngine.Tron;
     if (chainId === enums_1.ChainId.Solana)
-        return AddressFormat.Solana;
-    return AddressFormat.EVM;
+        return enums_1.ChainEngine.Solana;
+    return enums_1.ChainEngine.EVM;
 }
 function isTronAddress(address) {
     if (!address)
@@ -50,10 +46,26 @@ function tronAddressToEvmHex(tronAddress) {
     const addressBytes = decoded.slice(1, 21);
     return (0, viem_1.bytesToHex)(addressBytes);
 }
-// Normalizes address for comparison based on chain format
+// Normalizes address for comparison based on chain engine
 function normalizeAddress(chainId, address) {
-    const format = getAddressFormat(chainId);
-    if (format === AddressFormat.Tron || format === AddressFormat.Solana) {
+    const engine = getChainEngine(chainId);
+    return applyEngineNormalization(address, engine);
+}
+// Detects the chain engine from the address value alone (no chainId required).
+// Useful when a chain is not fixed (e.g. destinationChainIds = "any").
+function detectChainEngine(address) {
+    if (address.startsWith("0x"))
+        return enums_1.ChainEngine.EVM;
+    if (isTronAddress(address))
+        return enums_1.ChainEngine.Tron;
+    return enums_1.ChainEngine.Solana;
+}
+// Normalizes an address using only its own value — no chainId needed.
+function normalizeAddressByValue(address) {
+    return applyEngineNormalization(address, detectChainEngine(address));
+}
+function applyEngineNormalization(address, engine) {
+    if (engine === enums_1.ChainEngine.Tron || engine === enums_1.ChainEngine.Solana) {
         return address; // case-sensitive
     }
     return address.toLowerCase(); // EVM: case-insensitive
@@ -62,12 +74,13 @@ function normalizeAddress(chainId, address) {
 function addressEquals(chainId, a, b) {
     return normalizeAddress(chainId, a) === normalizeAddress(chainId, b);
 }
-// Checks if address is native token for the given chain
+// Checks if address is the native token for the given chain.
 function isNativeToken(address, chainId) {
-    if (chainId === enums_1.ChainId.Tron) {
+    const engine = getChainEngine(chainId);
+    if (engine === enums_1.ChainEngine.Tron) {
         return address === exports.TRON_NATIVE_ADDRESS;
     }
-    if (chainId === enums_1.ChainId.Solana) {
+    if (engine === enums_1.ChainEngine.Solana) {
         return address === solana_1.SYSTEM_PROGRAM;
     }
     return address.toLowerCase() === viem_1.zeroAddress;

package/dist/cjs/helpers/address.js.map

@@ -1 +1 @@
-{"version":3,"file":"address.js","sourceRoot":"","sources":["../../../src/helpers/address.ts"],"names":[],"mappings":";;;;;;AAcA,4CAIC;AAED,sCAOC;AAKD,kDAKC;AAGD,4CAMC;AAGD,sCAEC;AAGD,sCAQC;AA9DD,+BAA+C;AAC/C,gDAAwB;AACxB,0CAAyC;AACzC,iDAAsD;AAEtD,+CAA+C;AAClC,QAAA,mBAAmB,GAAG,oCAAoC,CAAC;AAExE,IAAY,aAIX;AAJD,WAAY,aAAa;IACrB,+CAAG,CAAA;IACH,iDAAI,CAAA;IACJ,qDAAM,CAAA;AACV,CAAC,EAJW,aAAa,6BAAb,aAAa,QAIxB;AAED,SAAgB,gBAAgB,CAAC,OAAe;IAC5C,IAAI,OAAO,KAAK,eAAO,CAAC,IAAI;QAAE,OAAO,aAAa,CAAC,IAAI,CAAC;IACxD,IAAI,OAAO,KAAK,eAAO,CAAC,MAAM;QAAE,OAAO,aAAa,CAAC,MAAM,CAAC;IAC5D,OAAO,aAAa,CAAC,GAAG,CAAC;AAC7B,CAAC;AAED,SAAgB,aAAa,CAAC,OAAe;IACzC,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3C,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACxC,4DAA4D;IAC5D,OAAO,IAAI,CAAC;AAChB,CAAC;AAED,8DAA8D;AAC9D,4EAA4E;AAC5E,oEAAoE;AACpE,SAAgB,mBAAmB,CAAC,WAAmB;IACnD,MAAM,OAAO,GAAG,cAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC;IACzC,4DAA4D;IAC5D,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1C,OAAO,IAAA,iBAAU,EAAC,YAAY,CAAC,CAAC;AACpC,CAAC;AAED,0DAA0D;AAC1D,SAAgB,gBAAgB,CAAC,OAAe,EAAE,OAAe;IAC7D,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,CAAC;IACzC,IAAI,MAAM,KAAK,aAAa,CAAC,IAAI,IAAI,MAAM,KAAK,aAAa,CAAC,MAAM,EAAE,CAAC;QACnE,OAAO,OAAO,CAAC,CAAC,iBAAiB;IACrC,CAAC;IACD,OAAO,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,wBAAwB;AAC1D,CAAC;AAED,wDAAwD;AACxD,SAAgB,aAAa,CAAC,OAAe,EAAE,CAAS,EAAE,CAAS;IAC/D,OAAO,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,gBAAgB,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;AACzE,CAAC;AAED,wDAAwD;AACxD,SAAgB,aAAa,CAAC,OAAe,EAAE,OAAgB;IAC3D,IAAI,OAAO,KAAK,eAAO,CAAC,IAAI,EAAE,CAAC;QAC3B,OAAO,OAAO,KAAK,2BAAmB,CAAC;IAC3C,CAAC;IACD,IAAI,OAAO,KAAK,eAAO,CAAC,MAAM,EAAE,CAAC;QAC7B,OAAO,OAAO,KAAK,uBAAc,CAAC;IACtC,CAAC;IACD,OAAO,OAAO,CAAC,WAAW,EAAE,KAAK,kBAAW,CAAC;AACjD,CAAC"}
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../../../src/helpers/address.ts"],"names":[],"mappings":"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"}

package/dist/cjs/helpers/evm-action.js

@@ -3,14 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.actionUsesTransactionCalls = actionUsesTransactionCalls;
 exports.getTransactionCalls = getTransactionCalls;
 const types_1 = require("../types");
-// Transaction and Sign712MetaMask actions carry transactionCalls;
+// Transaction and Sign712MetaMaskCaveats actions carry transactionCalls;
 // Sign712 (Permit/Permit2) and Sign7702Authorization do not.
 function actionUsesTransactionCalls(action) {
     return action.type === types_1.EvmActionKind.Transaction
-        || action.type === types_1.EvmActionKind.Sign712MetaMask;
+        || action.type === types_1.EvmActionKind.Sign712MetaMaskCaveats;
 }
 // For Transaction-type actions (non-AA), the call is in action.data directly.
-// For Sign712MetaMask-type actions (AA), the calls are in details.transactionCalls.
+// For Sign712MetaMaskCaveats-type actions (AA), the calls are in details.transactionCalls.
 function getTransactionCalls(action) {
     if (action.type === types_1.EvmActionKind.Transaction) {
         return [action.data];

package/dist/cjs/helpers/evm-action.js.map

@@ -1 +1 @@
-{"version":3,"file":"evm-action.js","sourceRoot":"","sources":["../../../src/helpers/evm-action.ts"],"names":[],"mappings":";;AAIA,gEAGC;AAID,kDAKC;AAhBD,oCAAgF;AAEhF,kEAAkE;AAClE,6DAA6D;AAC7D,SAAgB,0BAA0B,CAAC,MAAyB;IAChE,OAAO,MAAM,CAAC,IAAI,KAAK,qBAAa,CAAC,WAAW;WACzC,MAAM,CAAC,IAAI,KAAK,qBAAa,CAAC,eAAe,CAAC;AACzD,CAAC;AAED,8EAA8E;AAC9E,oFAAoF;AACpF,SAAgB,mBAAmB,CAAC,MAAyB;IACzD,IAAI,MAAM,CAAC,IAAI,KAAK,qBAAa,CAAC,WAAW,EAAE,CAAC;QAC5C,OAAO,CAAC,MAAM,CAAC,IAA0B,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,EAAE,gBAAgB,IAAI,EAAE,CAAC;AAClD,CAAC"}
+{"version":3,"file":"evm-action.js","sourceRoot":"","sources":["../../../src/helpers/evm-action.ts"],"names":[],"mappings":";;AAIA,gEAGC;AAID,kDAKC;AAhBD,oCAAgF;AAEhF,yEAAyE;AACzE,6DAA6D;AAC7D,SAAgB,0BAA0B,CAAC,MAAyB;IAChE,OAAO,MAAM,CAAC,IAAI,KAAK,qBAAa,CAAC,WAAW;WACzC,MAAM,CAAC,IAAI,KAAK,qBAAa,CAAC,sBAAsB,CAAC;AAChE,CAAC;AAED,8EAA8E;AAC9E,2FAA2F;AAC3F,SAAgB,mBAAmB,CAAC,MAAyB;IACzD,IAAI,MAAM,CAAC,IAAI,KAAK,qBAAa,CAAC,WAAW,EAAE,CAAC;QAC5C,OAAO,CAAC,MAAM,CAAC,IAA0B,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,MAAM,CAAC,OAAO,EAAE,gBAAgB,IAAI,EAAE,CAAC;AAClD,CAAC"}

package/dist/cjs/helpers/evm-gas-compensation-tx.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateEvmGasCompensationTx = validateEvmGasCompensationTx;
+const evm_calldata_1 = require("./evm-calldata");
+const evm_token_1 = require("./evm-token");
+const address_1 = require("./address");
+// Validates an EVM `{to, data, value}` triplet that is expected to encode a
+// gas-compensation transfer. `groups` are the gas-compensation groups
+// associated with this triplet's source (already filtered to the relevant
+// `(chainId, sender)` pair by the caller).
+//
+// Classification: dispatched on `triplet.data`:
+//   - `data === "0x"` → native compensation (data="0x", value > 0,
+//     and at least one group must carry a native token).
+//   - otherwise → ERC20 compensation (`triplet.to` matches some non-native
+//     group's tokenAddress, data is `transfer(...)`, value === "0").
+function validateEvmGasCompensationTx(triplet, groups, realChainId, basePath, codes) {
+    if (triplet.data === "0x") {
+        return validateNativeCompensation(triplet, groups, basePath, codes);
+    }
+    return validateErc20Compensation(triplet, groups, realChainId, basePath, codes);
+}
+function validateNativeCompensation(triplet, groups, basePath, codes) {
+    const violations = [];
+    // CRITICAL: data="0x" implies native — must have at least one native group.
+    const hasNativeGroup = groups.some(g => (0, evm_token_1.isNativeToken)(g.tokenAddress, g.realChainId));
+    if (!hasNativeGroup) {
+        violations.push({
+            code: codes.dataInvalid,
+            message: "data=\"0x\" implies native compensation but no group has a native token",
+            path: `${basePath}.data`,
+            expected: groups.map(g => g.tokenAddress),
+            actual: "0x",
+        });
+    }
+    // HIGH: native compensation value must parse and be > 0.
+    violations.push(...validateNativeValue(triplet.value, basePath, codes));
+    return violations;
+}
+function validateNativeValue(rawValue, basePath, codes) {
+    try {
+        if (BigInt(rawValue) <= 0n) {
+            return [{
+                    code: codes.valueInvalid,
+                    message: "native compensation must have value > 0",
+                    path: `${basePath}.value`,
+                    actual: rawValue,
+                }];
+        }
+        return [];
+    }
+    catch (error) {
+        return [{
+                code: codes.valueInvalid,
+                message: "native compensation value is not a valid number",
+                path: `${basePath}.value`,
+                actual: rawValue,
+                details: error,
+            }];
+    }
+}
+function validateErc20Compensation(triplet, groups, realChainId, basePath, codes) {
+    const violations = [];
+    // CRITICAL: `to` must equal some non-native group's tokenAddress.
+    const erc20Groups = groups.filter(g => !(0, evm_token_1.isNativeToken)(g.tokenAddress, g.realChainId));
+    const matches = erc20Groups.some(g => (0, address_1.normalizeAddress)(g.realChainId, g.tokenAddress)
+        === (0, address_1.normalizeAddress)(realChainId, triplet.to));
+    if (!matches) {
+        violations.push({
+            code: codes.toMismatch,
+            message: "ERC20 compensation `to` does not match any group's tokenAddress",
+            path: `${basePath}.to`,
+            expected: erc20Groups.map(g => g.tokenAddress),
+            actual: triplet.to,
+        });
+    }
+    // CRITICAL: data must be a valid ERC20 transfer calldata.
+    try {
+        (0, evm_calldata_1.decodeTransferCalldata)(triplet.data);
+    }
+    catch (error) {
+        violations.push({
+            code: codes.dataInvalid,
+            message: "ERC20 compensation data is not a valid transfer calldata",
+            path: `${basePath}.data`,
+            actual: triplet.data,
+            details: error,
+        });
+    }
+    // HIGH: ERC20 compensation must have value="0".
+    if (triplet.value !== "0") {
+        violations.push({
+            code: codes.valueInvalid,
+            message: "ERC20 compensation must have value=\"0\"",
+            path: `${basePath}.value`,
+            expected: "0",
+            actual: triplet.value,
+        });
+    }
+    return violations;
+}
+//# sourceMappingURL=evm-gas-compensation-tx.js.map

package/dist/cjs/helpers/evm-gas-compensation-tx.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evm-gas-compensation-tx.js","sourceRoot":"","sources":["../../../src/helpers/evm-gas-compensation-tx.ts"],"names":[],"mappings":"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"}

package/dist/cjs/helpers/evm-intent-id.js

@@ -20,7 +20,7 @@ function convertToIntentStruct(intent) {
         intentTimestamp: BigInt(intent.intentTimestamp),
         srcAllowedSender: (intent.srcAllowedSender ?? []),
         executionMetadata: (intent.executionMetadata ?? viem_1.zeroHash),
-        isAnyDlnMetadataAllowed: true,
+        isAnyDlnMetadataAllowed: !intent.dlnMetadata,
         dlnMetadata: (intent.dlnMetadata ?? "0x"),
         externalCallHash: (intent.externalCallHash ?? viem_1.zeroHash),
         combinedInteractions: "0x",

package/dist/cjs/helpers/evm-intent-id.js.map

@@ -1 +1 @@
-{"version":3,"file":"evm-intent-id.js","sourceRoot":"","sources":["../../../src/helpers/evm-intent-id.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"evm-intent-id.js","sourceRoot":"","sources":["../../../src/helpers/evm-intent-id.ts"],"names":[],"mappings":"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"}

package/dist/cjs/helpers/gas-compensation.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractGasCompensationGroups = extractGasCompensationGroups;
+const address_1 = require("./address");
+const subscription_to_chain_id_1 = require("../whitelists/subscription-to-chain-id");
+// Groups `gasCompensationInfo` entries from request.preHooks by
+// (chainId, tokenAddress, sender). One compensation hook per
+// unique group is expected to be appended to response.preHooks.
+// Groups with an unknown subscription chainId are skipped — they'll surface as
+// `UnknownSubscriptionId` via the trade-grouping pass.
+function extractGasCompensationGroups(request) {
+    const seen = new Set();
+    const groups = [];
+    for (const hook of request.preHooks ?? []) {
+        const info = hook.gasCompensationInfo;
+        if (!info)
+            continue;
+        const realChainId = (0, subscription_to_chain_id_1.resolveChainId)(info.chainId);
+        if (realChainId === undefined)
+            continue;
+        const key = `${realChainId}`
+            + `:${(0, address_1.normalizeAddress)(realChainId, info.tokenAddress)}`
+            + `:${(0, address_1.normalizeAddress)(realChainId, info.sender)}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        groups.push({
+            chainId: info.chainId,
+            realChainId,
+            tokenAddress: info.tokenAddress,
+            sender: info.sender,
+        });
+    }
+    return groups;
+}
+//# sourceMappingURL=gas-compensation.js.map

package/dist/cjs/helpers/gas-compensation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gas-compensation.js","sourceRoot":"","sources":["../../../src/helpers/gas-compensation.ts"],"names":[],"mappings":";;AAiBA,oEA8BC;AA7CD,uCAA6C;AAC7C,qFAAwE;AASxE,gEAAgE;AAChE,6DAA6D;AAC7D,gEAAgE;AAChE,+EAA+E;AAC/E,uDAAuD;AACvD,SAAgB,4BAA4B,CACxC,OAA8B;IAE9B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;QACxC,MAAM,IAAI,GAAG,IAAI,CAAC,mBAAmB,CAAC;QACtC,IAAI,CAAC,IAAI;YAAE,SAAS;QAEpB,MAAM,WAAW,GAAG,IAAA,yCAAc,EAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACjD,IAAI,WAAW,KAAK,SAAS;YAAE,SAAS;QAExC,MAAM,GAAG,GAAG,GAAG,WAAW,EAAE;cACtB,IAAI,IAAA,0BAAgB,EAAC,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC,EAAE;cACtD,IAAI,IAAA,0BAAgB,EAAC,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAEvD,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,SAAS;QAE5B,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAEd,MAAM,CAAC,IAAI,CAAC;YACR,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,WAAW;YACX,YAAY,EAAE,IAAI,CAAC,YAAY;YAC/B,MAAM,EAAE,IAAI,CAAC,MAAM;SACtB,CAAC,CAAC;IACP,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC"}

package/dist/cjs/helpers/placeholder.js

@@ -0,0 +1,174 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PlaceholderResolutionErrorReason = exports.HookMode = exports.SOLANA_DEFAULT_PLACEHOLDER_BYTE_COUNT = exports.EVM_DEFAULT_PLACEHOLDER_BYTE_COUNT = void 0;
+exports.encodePlaceholderAmount = encodePlaceholderAmount;
+exports.computeCumulativeTradeAmount = computeCumulativeTradeAmount;
+exports.resolveEagerPlaceholders = resolveEagerPlaceholders;
+const enums_1 = require("../types/enums");
+const address_1 = require("./address");
+const MIN_PLACEHOLDER_BYTE_COUNT = 1;
+const MAX_PLACEHOLDER_BYTE_COUNT = 32;
+exports.EVM_DEFAULT_PLACEHOLDER_BYTE_COUNT = MAX_PLACEHOLDER_BYTE_COUNT;
+exports.SOLANA_DEFAULT_PLACEHOLDER_BYTE_COUNT = 8;
+var HookMode;
+(function (HookMode) {
+    HookMode[HookMode["PreHooks"] = 0] = "PreHooks";
+    HookMode[HookMode["PostHooks"] = 1] = "PostHooks";
+})(HookMode || (exports.HookMode = HookMode = {}));
+var PlaceholderResolutionErrorReason;
+(function (PlaceholderResolutionErrorReason) {
+    PlaceholderResolutionErrorReason[PlaceholderResolutionErrorReason["MissingTokenOrAddress"] = 0] = "MissingTokenOrAddress";
+    PlaceholderResolutionErrorReason[PlaceholderResolutionErrorReason["NegativeAmount"] = 1] = "NegativeAmount";
+    PlaceholderResolutionErrorReason[PlaceholderResolutionErrorReason["Overflow"] = 2] = "Overflow";
+    PlaceholderResolutionErrorReason[PlaceholderResolutionErrorReason["InvalidByteCount"] = 3] = "InvalidByteCount";
+    PlaceholderResolutionErrorReason[PlaceholderResolutionErrorReason["InvalidAdditionalAmount"] = 4] = "InvalidAdditionalAmount";
+    PlaceholderResolutionErrorReason[PlaceholderResolutionErrorReason["NoMatchingTradeOrAdditional"] = 5] = "NoMatchingTradeOrAdditional";
+})(PlaceholderResolutionErrorReason || (exports.PlaceholderResolutionErrorReason = PlaceholderResolutionErrorReason = {}));
+// Encodes a non-negative integer as a zero-padded hex string (no "0x" prefix),
+// fitting exactly `byteCount` bytes, using the chain engine's endianness.
+// Solana: little-endian. EVM/Tron: big-endian.
+// `byteCount` must be an integer in
+// [MIN_PLACEHOLDER_BYTE_COUNT, MAX_PLACEHOLDER_BYTE_COUNT].
+function encodePlaceholderAmount(amount, byteCount, engine) {
+    if (!isValidByteCount(byteCount)) {
+        return { ok: false, reason: PlaceholderResolutionErrorReason.InvalidByteCount };
+    }
+    if (amount < 0n) {
+        return { ok: false, reason: PlaceholderResolutionErrorReason.NegativeAmount };
+    }
+    const maxValue = (1n << BigInt(byteCount * 8)) - 1n;
+    if (amount > maxValue) {
+        return { ok: false, reason: PlaceholderResolutionErrorReason.Overflow };
+    }
+    if (engine === enums_1.ChainEngine.Solana) { // Use little-endian for Solana
+        const bytes = [];
+        let value = amount;
+        for (let i = 0; i < byteCount; i++) {
+            bytes.push((value & 0xffn).toString(16).padStart(2, "0"));
+            value >>= 8n;
+        }
+        return { ok: true, hex: bytes.join("") };
+    }
+    // Use big-endian (EVM/Tron): simple hex conversion with left-padding.
+    return { ok: true, hex: amount.toString(16).padStart(byteCount * 2, "0") };
+}
+function isValidByteCount(byteCount) {
+    return Number.isInteger(byteCount)
+        && byteCount >= MIN_PLACEHOLDER_BYTE_COUNT
+        && byteCount <= MAX_PLACEHOLDER_BYTE_COUNT;
+}
+// Sums the trade amount matching the placeholder's (chainId, tokenAddress, address).
+// preHooks: sums trade.srcChainTokenIn.amount across trades where
+//   trade.srcChainTokenIn.{chainId,address} and trade.srcChainAuthorityAddress match.
+// postHooks: sums trade.dstChainTokenOut.amount across trades where
+//   trade.dstChainTokenOut.{chainId,address} and trade.dstChainTokenOutRecipient match.
+// In quote mode authority/recipient is undefined — such trades are skipped.
+function computeCumulativeTradeAmount(trades, mode, chainId, tokenAddress, address) {
+    let sum = 0n;
+    let matchCount = 0;
+    for (const trade of trades) {
+        const tradeChainId = mode === HookMode.PreHooks
+            ? trade.srcChainTokenIn.chainId
+            : trade.dstChainTokenOut.chainId;
+        if (tradeChainId !== chainId)
+            continue;
+        const tradeAuthority = mode === HookMode.PreHooks
+            ? trade.srcChainAuthorityAddress
+            : trade.dstChainTokenOutRecipient;
+        if (tradeAuthority === undefined)
+            continue;
+        const tradeToken = mode === HookMode.PreHooks
+            ? trade.srcChainTokenIn.address
+            : trade.dstChainTokenOut.address;
+        if (!(0, address_1.addressEquals)(chainId, tradeToken, tokenAddress))
+            continue;
+        if (!(0, address_1.addressEquals)(chainId, tradeAuthority, address))
+            continue;
+        const amount = mode === HookMode.PreHooks
+            ? trade.srcChainTokenIn.amount
+            : trade.dstChainTokenOut.amount;
+        sum += BigInt(amount);
+        matchCount++;
+    }
+    return { cumulative: sum, matchCount };
+}
+// Applies eager-placeholder substitution to a hex string (calldata or value).
+// Markers: `{name}` or `{name.N}` (N = byte count).
+// Deferred placeholders are not touched — their markers remain in the output.
+// If any eager placeholder cannot be resolved, its marker is left intact and the
+// error is collected into `errors`; callers decide how to report it.
+function resolveEagerPlaceholders(data, hookChainId, placeholders, trades, mode) {
+    const engine = (0, address_1.getChainEngine)(hookChainId);
+    const defaultByteCount = engine === enums_1.ChainEngine.Solana
+        ? exports.SOLANA_DEFAULT_PLACEHOLDER_BYTE_COUNT
+        : exports.EVM_DEFAULT_PLACEHOLDER_BYTE_COUNT;
+    let result = data;
+    const errors = [];
+    for (const placeholder of placeholders) {
+        if (placeholder.type === enums_1.PlaceholderType.Deferred)
+            continue;
+        // Eager placeholder — type is either explicitly 'eager' or undefined (default).
+        if (placeholder.tokenAddress === undefined
+            || placeholder.address === undefined) {
+            // Zod guards this at the schema level; defensive branch for callers
+            // that bypass structural validation.
+            errors.push({
+                nameVariable: placeholder.nameVariable,
+                reason: PlaceholderResolutionErrorReason.MissingTokenOrAddress,
+            });
+            continue;
+        }
+        let additional = 0n;
+        if (placeholder.additionalAmount !== undefined) {
+            try {
+                additional = BigInt(placeholder.additionalAmount);
+            }
+            catch (error) {
+                errors.push({
+                    nameVariable: placeholder.nameVariable,
+                    reason: PlaceholderResolutionErrorReason.InvalidAdditionalAmount,
+                    details: error,
+                });
+                continue;
+            }
+        }
+        const { cumulative, matchCount } = computeCumulativeTradeAmount(trades, mode, hookChainId, placeholder.tokenAddress, placeholder.address);
+        const expectedAmount = cumulative + additional;
+        const nameEscaped = escapeRegex(placeholder.nameVariable);
+        const markerRegex = new RegExp(`\\{${nameEscaped}(?:\\.(\\d+))?\\}`, "g");
+        // MEDIUM: when no trade matches and no `additionalAmount` is supplied,
+        // the API rejects the request. Here we are mirroring this logic.
+        if (matchCount === 0
+            && placeholder.additionalAmount === undefined
+            && markerRegex.test(result)) {
+            errors.push({
+                nameVariable: placeholder.nameVariable,
+                reason: PlaceholderResolutionErrorReason.NoMatchingTradeOrAdditional,
+            });
+            // Reset RegExp.lastIndex before the `replace` below.
+            markerRegex.lastIndex = 0;
+            // Skip substitution — leave marker in `result` so calldata comparison
+            // surfaces any mutated value as a separate violation.
+            continue;
+        }
+        result = result.replace(markerRegex, (match, byteCountStr) => {
+            const byteCount = byteCountStr
+                ? parseInt(byteCountStr, 10)
+                : defaultByteCount;
+            const encoded = encodePlaceholderAmount(expectedAmount, byteCount, engine);
+            if (!encoded.ok) {
+                errors.push({
+                    nameVariable: placeholder.nameVariable,
+                    reason: encoded.reason,
+                });
+                return match;
+            }
+            return encoded.hex;
+        });
+    }
+    return { resolved: result, errors };
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//# sourceMappingURL=placeholder.js.map

package/dist/cjs/helpers/placeholder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placeholder.js","sourceRoot":"","sources":["../../../src/helpers/placeholder.ts"],"names":[],"mappings":"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"}