@sun-protocol/sun-sdk-protocols 0.1.0-beta.0

package/README.md

@@ -0,0 +1,30 @@
+# @sun-protocol/sun-sdk-protocols
+
+High-level SUN SDK workflows for swaps, PSM, SunPump, liquidity, and positions.
+
+## Install
+
+```bash
+npm install @sun-protocol/sun-sdk-protocols @sun-protocol/sun-sdk-runtime
+```
+
+## Example
+
+```ts
+import { SunSDK } from '@sun-protocol/sun-sdk-protocols'
+
+const sun = await SunSDK.create({ network: 'mainnet' })
+const quote = await sun.swap.router.quote({
+  tokenIn: 'TRX',
+  tokenOut: token,
+  amountIn: '1000000',
+})
+```
+
+The root entry exports `SunSDK`, protocol contexts, plan executors, approval helpers, and all public workflow types. Subpath entry points are available at `/swap`, `/liquidity`, `/positions`, and `/pump`.
+
+This package orchestrates API, runtime, and protocol primitives. It does not discover a global wallet: applications explicitly provide a `TronClient`, a `WalletAdapter`, or a composed runtime when chain access is needed.
+
+Requires Node.js 20. HTTP-only operations need `fetch`; chain execution needs a compatible runtime adapter.
+
+[Full API documentation](https://github.com/sun-protocol/sun-sdk/blob/main/docs/sdk/api/protocols.md)

package/dist/chunk-5XDX5563.js

@@ -0,0 +1,99 @@
+import {
+  normalizeTronAddress
+} from "./chunk-C2YCVBPI.js";
+
+// src/usdt-transfer.ts
+import { SDKError } from "@sun-protocol/sun-sdk-core";
+async function usdtValidateTransfer(input) {
+  if (input.transfersUsdt === false) return { status: "allowed" };
+  if (input.transfersUsdt !== true) return { status: "unknown", reason: "CHECK_FAILED" };
+  if (input.sources.length === 0) return { status: "unknown", reason: "MISSING_TRANSFER_SOURCE" };
+  try {
+    const paused = await input.reader.paused();
+    if (typeof paused !== "boolean") throw new Error("Invalid paused result");
+    if (paused) return { status: "blocked", reason: "USDT_PAUSED" };
+    const sources = /* @__PURE__ */ new Map();
+    for (const source of input.sources) {
+      const address = normalizeTronAddress(source.address);
+      sources.set(address, { ...source, address });
+    }
+    const checks = await Promise.all([...sources.values()].map(async (source) => {
+      const blacklisted = await input.reader.isBlackListed(source.address);
+      if (typeof blacklisted !== "boolean") throw new Error("Invalid blacklist result");
+      return { source, blacklisted };
+    }));
+    const blocked = checks.filter((check) => check.blacklisted).map((check) => check.source);
+    return blocked.length > 0 ? { status: "blocked", reason: "USDT_SOURCE_BLACKLISTED", sources: blocked } : { status: "allowed" };
+  } catch {
+    return { status: "unknown", reason: "CHECK_FAILED" };
+  }
+}
+function parseTransferContext(context, action) {
+  const data = action.metadata?.usdtTransfer;
+  if (!data) throw new Error("Missing USDT transfer context");
+  if (data.network !== context.network || typeof data.transfersUsdt !== "boolean" || !Array.isArray(data.sources)) {
+    throw new Error("Invalid USDT transfer context; rebuild the plan");
+  }
+  const sources = data.sources.map((source) => {
+    if (!source || typeof source.address !== "string" || source.role !== "v3-pool" && source.role !== "position-manager") {
+      throw new Error("Invalid USDT transfer source");
+    }
+    const address = normalizeTronAddress(source.address);
+    if (source.role === "position-manager" && address !== normalizeTronAddress(action.target)) {
+      throw new Error("USDT sweep source does not match the position manager");
+    }
+    return { address, role: source.role };
+  });
+  if (!data.transfersUsdt && sources.length > 0) throw new Error("Unexpected USDT sources");
+  return { network: context.network, transfersUsdt: data.transfersUsdt, sources };
+}
+function boolRead(target, name, address) {
+  return {
+    target,
+    functionSelector: name === "paused" ? "paused()" : "isBlackListed(address)",
+    parameters: address === void 0 ? [] : [{ type: "address", value: address }],
+    abiFunction: {
+      type: "function",
+      name,
+      stateMutability: "view",
+      inputs: name === "paused" ? [] : [{ name: "_user", type: "address" }],
+      outputs: [{ name: "", type: "bool" }]
+    }
+  };
+}
+async function assertUsdtTransfer(context, action) {
+  let result;
+  if (!action.metadata?.usdtTransfer) {
+    result = { status: "unknown", reason: "MISSING_TRANSFER_SOURCE" };
+  } else {
+    try {
+      const data = parseTransferContext(context, action);
+      if (data.transfersUsdt && !data.sources.some((source) => source.role === "v3-pool")) {
+        result = { status: "unknown", reason: "MISSING_TRANSFER_SOURCE" };
+      } else {
+        const read = (name, address) => {
+          if (!context.runtime) throw new Error("USDT transfer validation requires a runtime");
+          return context.runtime.readContract(boolRead(context.chain.contracts.usdt, name, address));
+        };
+        result = await usdtValidateTransfer({
+          ...data,
+          reader: { paused: () => read("paused"), isBlackListed: (address) => read("isBlackListed", address) }
+        });
+      }
+    } catch {
+      result = { status: "unknown", reason: "CHECK_FAILED" };
+    }
+  }
+  if (result.status === "allowed") return;
+  throw new SDKError(
+    result.status === "blocked" ? "SDK_USDT_TRANSFER_BLOCKED" : "SDK_USDT_TRANSFER_UNKNOWN",
+    result.status === "blocked" ? "USDT transfer is currently restricted" : "Unable to verify USDT transfer status",
+    { ...result, usdtAddress: context.chain.contracts.usdt, actionId: action.id }
+  );
+}
+
+export {
+  usdtValidateTransfer,
+  assertUsdtTransfer
+};
+//# sourceMappingURL=chunk-5XDX5563.js.map

package/dist/chunk-5XDX5563.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/usdt-transfer.ts"],"sourcesContent":["import { SDKError, type ContractCallAction, type Network, type TronAddress } from '@sun-protocol/sun-sdk-core'\nimport type { ContractRead } from '@sun-protocol/sun-sdk-runtime'\nimport type { ProtocolsContext } from './context.js'\nimport { normalizeTronAddress } from './internal/tokens.js'\n\nexport interface UsdtReader {\n  paused(): Promise<boolean>\n  isBlackListed(address: string): Promise<boolean>\n}\n\nexport interface TransferSource {\n  readonly address: string\n  readonly role: 'v3-pool' | 'position-manager'\n}\n\nexport type UsdtTransferValidationResult =\n  | { readonly status: 'allowed' }\n  | { readonly status: 'blocked'; readonly reason: 'USDT_PAUSED' }\n  | { readonly status: 'blocked'; readonly reason: 'USDT_SOURCE_BLACKLISTED'; readonly sources: readonly TransferSource[] }\n  | { readonly status: 'unknown'; readonly reason: 'MISSING_TRANSFER_SOURCE' | 'CHECK_FAILED' }\n\n/** Applies the USDT paused/blacklist check. Unknown results never authorize submission. */\nexport async function usdtValidateTransfer(input: {\n  readonly reader: UsdtReader\n  readonly transfersUsdt: boolean\n  readonly sources: readonly TransferSource[]\n}): Promise<UsdtTransferValidationResult> {\n  if (input.transfersUsdt === false) return { status: 'allowed' }\n  if (input.transfersUsdt !== true) return { status: 'unknown', reason: 'CHECK_FAILED' }\n  if (input.sources.length === 0) return { status: 'unknown', reason: 'MISSING_TRANSFER_SOURCE' }\n\n  try {\n    const paused = await input.reader.paused()\n    if (typeof paused !== 'boolean') throw new Error('Invalid paused result')\n    if (paused) return { status: 'blocked', reason: 'USDT_PAUSED' }\n\n    const sources = new Map<string, TransferSource>()\n    for (const source of input.sources) {\n      const address = normalizeTronAddress(source.address)\n      sources.set(address, { ...source, address })\n    }\n    const checks = await Promise.all([...sources.values()].map(async (source) => {\n      const blacklisted = await input.reader.isBlackListed(source.address)\n      if (typeof blacklisted !== 'boolean') throw new Error('Invalid blacklist result')\n      return { source, blacklisted }\n    }))\n    const blocked = checks.filter((check) => check.blacklisted).map((check) => check.source)\n    return blocked.length > 0\n      ? { status: 'blocked', reason: 'USDT_SOURCE_BLACKLISTED', sources: blocked }\n      : { status: 'allowed' }\n  } catch {\n    return { status: 'unknown', reason: 'CHECK_FAILED' }\n  }\n}\n\n/** Static facts about an SDK-built action; never stores a previous check result. */\nexport interface UsdtTransferContext {\n  readonly network: Network\n  readonly transfersUsdt: boolean\n  readonly sources: readonly TransferSource[]\n}\n\nfunction parseTransferContext(context: ProtocolsContext, action: ContractCallAction): UsdtTransferContext {\n  const data = action.metadata?.usdtTransfer as Partial<UsdtTransferContext> | undefined\n  if (!data) throw new Error('Missing USDT transfer context')\n  if (data.network !== context.network ||\n    typeof data.transfersUsdt !== 'boolean' || !Array.isArray(data.sources)) {\n    throw new Error('Invalid USDT transfer context; rebuild the plan')\n  }\n  const sources = data.sources.map((source: TransferSource) => {\n    if (!source || typeof source.address !== 'string' ||\n      (source.role !== 'v3-pool' && source.role !== 'position-manager')) {\n      throw new Error('Invalid USDT transfer source')\n    }\n    const address = normalizeTronAddress(source.address)\n    if (source.role === 'position-manager' && address !== normalizeTronAddress(action.target)) {\n      throw new Error('USDT sweep source does not match the position manager')\n    }\n    return { address, role: source.role }\n  })\n  if (!data.transfersUsdt && sources.length > 0) throw new Error('Unexpected USDT sources')\n  return { network: context.network, transfersUsdt: data.transfersUsdt, sources }\n}\n\nfunction boolRead(target: TronAddress, name: 'paused' | 'isBlackListed', address?: string): ContractRead {\n  return {\n    target,\n    functionSelector: name === 'paused' ? 'paused()' : 'isBlackListed(address)',\n    parameters: address === undefined ? [] : [{ type: 'address', value: address }],\n    abiFunction: {\n      type: 'function', name, stateMutability: 'view',\n      inputs: name === 'paused' ? [] : [{ name: '_user', type: 'address' }],\n      outputs: [{ name: '', type: 'bool' }],\n    },\n  }\n}\n\n/** Internal execution guard, shared by the two protocol-specific executors. */\nexport async function assertUsdtTransfer(context: ProtocolsContext, action: ContractCallAction): Promise<void> {\n  let result: UsdtTransferValidationResult\n  if (!action.metadata?.usdtTransfer) {\n    result = { status: 'unknown', reason: 'MISSING_TRANSFER_SOURCE' }\n  } else {\n    try {\n      const data = parseTransferContext(context, action)\n      if (data.transfersUsdt && !data.sources.some((source) => source.role === 'v3-pool')) {\n        result = { status: 'unknown', reason: 'MISSING_TRANSFER_SOURCE' }\n      } else {\n        const read = (name: 'paused' | 'isBlackListed', address?: string) => {\n          if (!context.runtime) throw new Error('USDT transfer validation requires a runtime')\n          return context.runtime.readContract<boolean>(boolRead(context.chain.contracts.usdt, name, address))\n        }\n        result = await usdtValidateTransfer({\n          ...data,\n          reader: { paused: () => read('paused'), isBlackListed: (address) => read('isBlackListed', address) },\n        })\n      }\n    } catch {\n      result = { status: 'unknown', reason: 'CHECK_FAILED' }\n    }\n  }\n  if (result.status === 'allowed') return\n  throw new SDKError(\n    result.status === 'blocked' ? 'SDK_USDT_TRANSFER_BLOCKED' : 'SDK_USDT_TRANSFER_UNKNOWN',\n    result.status === 'blocked' ? 'USDT transfer is currently restricted' : 'Unable to verify USDT transfer status',\n    { ...result, usdtAddress: context.chain.contracts.usdt, actionId: action.id },\n  )\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-C2YCVBPI.js

@@ -0,0 +1,212 @@
+import {
+  normalizeBaseUnitAmount,
+  requireRuntime
+} from "./chunk-VFVKMC4H.js";
+
+// src/approval/check.ts
+async function readClassicAllowance(runtime, requirement) {
+  if (requirement.asset.type === "native") return "0";
+  const result = await runtime.readContract({
+    target: requirement.asset.token,
+    functionSelector: "allowance(address,address)",
+    parameters: [
+      { type: "address", value: requirement.owner },
+      { type: "address", value: requirement.spender }
+    ],
+    outputs: [{ type: "uint256", name: "allowance" }]
+  });
+  return BigInt(result).toString();
+}
+async function checkClassicAllowance(runtime, requirement) {
+  if (requirement.asset.type === "native") {
+    return { allowance: requirement.amount, sufficient: true };
+  }
+  const allowance = await readClassicAllowance(runtime, requirement);
+  return {
+    allowance,
+    sufficient: BigInt(allowance) >= BigInt(requirement.amount)
+  };
+}
+
+// src/approval/classic.ts
+import {
+  MaxUint256,
+  createApproveAction
+} from "@sun-protocol/sun-sdk-core";
+function buildClassicApproveAction(requirement, options = {}) {
+  if (requirement.asset.type === "native") return void 0;
+  return createApproveAction({
+    id: `approve-${requirement.asset.token}-${requirement.spender}`,
+    target: requirement.asset.token,
+    spender: requirement.spender,
+    amount: options.amount === "exact" ? requirement.amount : MaxUint256.toString(),
+    ...options.feeLimit !== void 0 ? { feeLimit: options.feeLimit } : {}
+  });
+}
+
+// src/approval/plan.ts
+import { SDKError } from "@sun-protocol/sun-sdk-core";
+async function planApproval(context, requirement, options = {}) {
+  const mode = options.mode ?? "auto";
+  normalizeBaseUnitAmount(requirement.amount, "approval amount");
+  if (requirement.asset.type === "native") {
+    return {
+      mode,
+      requirement,
+      allowance: requirement.amount,
+      sufficient: true,
+      actions: []
+    };
+  }
+  if (mode === "none") {
+    return { mode, requirement, actions: [] };
+  }
+  if (mode === "permit2") {
+    throw new SDKError(
+      "SDK_WALLET_CAPABILITY_ERROR",
+      "Permit2 approval is unavailable until a Permit2 adapter is configured",
+      { mode, token: requirement.asset.token }
+    );
+  }
+  const runtime = requireRuntime(context, "Token allowance check");
+  const check = await checkClassicAllowance(runtime, requirement);
+  if (check.sufficient) {
+    return {
+      mode,
+      requirement,
+      allowance: check.allowance,
+      sufficient: true,
+      actions: []
+    };
+  }
+  const action = buildClassicApproveAction(requirement, options);
+  return {
+    mode,
+    requirement,
+    allowance: check.allowance,
+    sufficient: false,
+    actions: action ? [action] : []
+  };
+}
+
+// src/internal/reads.ts
+import { SDKError as SDKError2 } from "@sun-protocol/sun-sdk-core";
+async function readRequiredContract(context, call, operation) {
+  const runtime = requireRuntime(context, operation);
+  const value = await runtime.readContract(call);
+  if (value === void 0 || value === null) {
+    throw new SDKError2("SDK_CONTRACT_ERROR", `${operation} returned an empty result`, { call });
+  }
+  return value;
+}
+async function readMulticallRequired(context, calls, operation) {
+  const runtime = requireRuntime(context, operation);
+  const results = await runtime.multicall(calls);
+  return results.map((result, index) => {
+    if (!result.success || result.value === void 0) {
+      throw new SDKError2("SDK_CONTRACT_ERROR", `${operation} multicall item failed`, {
+        index,
+        call: calls[index],
+        error: result.error
+      });
+    }
+    return result.value;
+  });
+}
+
+// src/internal/tokens.ts
+import { getWrappedNativeAddress } from "@sun-protocol/sun-sdk-chains";
+import {
+  Percent,
+  SDKError as SDKError3,
+  TRON_ZERO_ADDRESS,
+  Token,
+  assertTronAddress
+} from "@sun-protocol/sun-sdk-core";
+import {
+  evmHexToTronAddress as evmHexToTronAddressV2,
+  tronAddressToEvmHex
+} from "@sun-protocol/sun-sdk-sunswap-v2";
+var PERCENT_PATTERN = /^(\d+)(?:\.(\d+))?%$/;
+function isNativeTrxInput(context, token) {
+  return token.toUpperCase() === "TRX" || token === context.chain.contracts.trx;
+}
+function evmHexToTronAddress(address, label = "address") {
+  const normalized = address.startsWith("0x") ? address.toLowerCase() : `0x${address.toLowerCase()}`;
+  return evmHexToTronAddressV2(normalized, label);
+}
+function tronAddressToEvmAddress(address, label = "address") {
+  return `0x${tronAddressToEvmHex(assertTronAddress(address, label))}`;
+}
+function normalizeTronAddress(address, label = "address") {
+  if (/^41[0-9a-fA-F]{40}$/.test(address)) return evmHexToTronAddress(`0x${address.slice(2)}`, label);
+  if (/^0x[0-9a-fA-F]{40}$/.test(address)) return evmHexToTronAddress(address, label);
+  return evmHexToTronAddress(tronAddressToEvmAddress(address, label), label);
+}
+function normalizeProtocolToken(context, token, label, metadata = {}) {
+  const wrappedContractAddress = getWrappedNativeAddress(context.network);
+  const kind = isNativeTrxInput(context, token) ? "native" : "token";
+  const contractAddress = kind === "native" ? TRON_ZERO_ADDRESS : assertTronAddress(token, label);
+  const mathAddress = kind === "native" ? wrappedContractAddress : contractAddress;
+  const evmAddress = `0x${tronAddressToEvmHex(mathAddress)}`.toLowerCase();
+  return {
+    kind,
+    input: token,
+    contractAddress,
+    wrappedContractAddress,
+    token: new Token(
+      context.chain.uniswapChainId,
+      evmAddress,
+      metadata.decimals ?? 6,
+      metadata.symbol,
+      metadata.name,
+      true
+    )
+  };
+}
+function parseLiquidityPercentageInput(value, label) {
+  if (value instanceof Percent) return value;
+  const match = PERCENT_PATTERN.exec(value);
+  if (!match) {
+    throw new SDKError3("SDK_INVALID_ARGUMENT", `${label} must be a percentage string`, {
+      label,
+      percentage: value
+    });
+  }
+  const whole = match[1] ?? "0";
+  const fraction = match[2] ?? "";
+  const scale = 10n ** BigInt(fraction.length);
+  const percentageUnits = BigInt(whole) * scale + BigInt(fraction || "0");
+  return new Percent(percentageUnits.toString(), (100n * scale).toString());
+}
+function normalizeLiquidityPercentage(value, label) {
+  const percent = parseLiquidityPercentageInput(value, label);
+  if (percent.equalTo(0)) {
+    throw new SDKError3("SDK_INVALID_ARGUMENT", `${label} must be greater than 0%`, {
+      label,
+      percentage: percent.toSignificant()
+    });
+  }
+  if (percent.greaterThan(1)) {
+    throw new SDKError3("SDK_INVALID_ARGUMENT", `${label} must be at most 100%`, {
+      label,
+      percentage: percent.toSignificant()
+    });
+  }
+  return percent;
+}
+
+export {
+  readClassicAllowance,
+  checkClassicAllowance,
+  buildClassicApproveAction,
+  planApproval,
+  readRequiredContract,
+  readMulticallRequired,
+  evmHexToTronAddress,
+  tronAddressToEvmAddress,
+  normalizeTronAddress,
+  normalizeProtocolToken,
+  normalizeLiquidityPercentage
+};
+//# sourceMappingURL=chunk-C2YCVBPI.js.map

package/dist/chunk-C2YCVBPI.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/approval/check.ts","../src/approval/classic.ts","../src/approval/plan.ts","../src/internal/reads.ts","../src/internal/tokens.ts"],"sourcesContent":["import type { Runtime } from '@sun-protocol/sun-sdk-runtime'\nimport type { ApprovalRequirement } from './types.js'\n\nexport async function readClassicAllowance(\n  runtime: Runtime,\n  requirement: ApprovalRequirement,\n): Promise<string> {\n  if (requirement.asset.type === 'native') return '0'\n  const result = await runtime.readContract<string | number | bigint>({\n    target: requirement.asset.token,\n    functionSelector: 'allowance(address,address)',\n    parameters: [\n      { type: 'address', value: requirement.owner },\n      { type: 'address', value: requirement.spender },\n    ],\n    outputs: [{ type: 'uint256', name: 'allowance' }],\n  })\n  return BigInt(result).toString()\n}\n\nexport async function checkClassicAllowance(\n  runtime: Runtime,\n  requirement: ApprovalRequirement,\n): Promise<{ allowance: string; sufficient: boolean }> {\n  if (requirement.asset.type === 'native') {\n    return { allowance: requirement.amount, sufficient: true }\n  }\n  const allowance = await readClassicAllowance(runtime, requirement)\n  return {\n    allowance,\n    sufficient: BigInt(allowance) >= BigInt(requirement.amount),\n  }\n}\n","import {\n  MaxUint256,\n  createApproveAction,\n  type ContractCallAction,\n} from '@sun-protocol/sun-sdk-core'\nimport type {\n  ApprovalPlanOptions,\n  ApprovalRequirement,\n} from './types.js'\n\nexport function buildClassicApproveAction(\n  requirement: ApprovalRequirement,\n  options: Pick<ApprovalPlanOptions, 'amount' | 'feeLimit'> = {},\n): ContractCallAction | undefined {\n  if (requirement.asset.type === 'native') return undefined\n  return createApproveAction({\n    id: `approve-${requirement.asset.token}-${requirement.spender}`,\n    target: requirement.asset.token,\n    spender: requirement.spender,\n    amount: options.amount === 'exact'\n      ? requirement.amount\n      : MaxUint256.toString(),\n    ...(options.feeLimit !== undefined ? { feeLimit: options.feeLimit } : {}),\n  })\n}\n","import { SDKError } from '@sun-protocol/sun-sdk-core'\nimport { normalizeBaseUnitAmount } from '../common.js'\nimport {\n  requireRuntime,\n  type ProtocolsContext,\n} from '../context.js'\nimport { checkClassicAllowance } from './check.js'\nimport { buildClassicApproveAction } from './classic.js'\nimport type {\n  ApprovalPlanOptions,\n  ApprovalPlanResult,\n  ApprovalRequirement,\n} from './types.js'\n\n/** Plans a token approval without signing or broadcasting it. */\nexport async function planApproval(\n  context: ProtocolsContext,\n  requirement: ApprovalRequirement,\n  options: ApprovalPlanOptions = {},\n): Promise<ApprovalPlanResult> {\n  const mode = options.mode ?? 'auto'\n  normalizeBaseUnitAmount(requirement.amount, 'approval amount')\n\n  if (requirement.asset.type === 'native') {\n    return {\n      mode,\n      requirement,\n      allowance: requirement.amount,\n      sufficient: true,\n      actions: [],\n    }\n  }\n\n  if (mode === 'none') {\n    return { mode, requirement, actions: [] }\n  }\n\n  if (mode === 'permit2') {\n    throw new SDKError(\n      'SDK_WALLET_CAPABILITY_ERROR',\n      'Permit2 approval is unavailable until a Permit2 adapter is configured',\n      { mode, token: requirement.asset.token },\n    )\n  }\n\n  const runtime = requireRuntime(context, 'Token allowance check')\n  const check = await checkClassicAllowance(runtime, requirement)\n  if (check.sufficient) {\n    return {\n      mode,\n      requirement,\n      allowance: check.allowance,\n      sufficient: true,\n      actions: [],\n    }\n  }\n\n  const action = buildClassicApproveAction(requirement, options)\n  return {\n    mode,\n    requirement,\n    allowance: check.allowance,\n    sufficient: false,\n    actions: action ? [action] : [],\n  }\n}\n","import { SDKError } from '@sun-protocol/sun-sdk-core'\nimport type { ContractRead, MulticallResult } from '@sun-protocol/sun-sdk-runtime'\nimport {\n  requireRuntime,\n  type ProtocolsContext,\n} from '../context.js'\n\nexport async function readRequiredContract<T>(\n  context: ProtocolsContext,\n  call: ContractRead,\n  operation: string,\n): Promise<T> {\n  const runtime = requireRuntime(context, operation)\n  const value = await runtime.readContract<T>(call)\n  if (value === undefined || value === null) {\n    throw new SDKError('SDK_CONTRACT_ERROR', `${operation} returned an empty result`, { call })\n  }\n  return value\n}\n\nexport async function readMulticallRequired<T>(\n  context: ProtocolsContext,\n  calls: readonly ContractRead[],\n  operation: string,\n): Promise<readonly T[]> {\n  const runtime = requireRuntime(context, operation)\n  const results = await runtime.multicall<T>(calls)\n  return results.map((result: MulticallResult<T>, index: number) => {\n    if (!result.success || result.value === undefined) {\n      throw new SDKError('SDK_CONTRACT_ERROR', `${operation} multicall item failed`, {\n        index,\n        call: calls[index],\n        error: result.error,\n      })\n    }\n    return result.value\n  })\n}\n","import { getWrappedNativeAddress } from '@sun-protocol/sun-sdk-chains'\nimport {\n  Percent,\n  SDKError,\n  TRON_ZERO_ADDRESS,\n  Token,\n  assertTronAddress,\n  type TronAddress,\n} from '@sun-protocol/sun-sdk-core'\nimport {\n  evmHexToTronAddress as evmHexToTronAddressV2,\n  tronAddressToEvmHex,\n} from '@sun-protocol/sun-sdk-sunswap-v2'\nimport type { ProtocolsContext } from '../context.js'\nimport type { SlippageInput } from '../types/common.js'\n\nconst PERCENT_PATTERN = /^(\\d+)(?:\\.(\\d+))?%$/\n\nexport type ProtocolTokenKind = 'native' | 'token'\n\nexport interface ProtocolToken {\n  readonly kind: ProtocolTokenKind\n  readonly input: string\n  readonly contractAddress: TronAddress\n  readonly wrappedContractAddress: TronAddress\n  readonly token: Token\n}\n\nexport function isNativeTrxInput(context: ProtocolsContext, token: string): boolean {\n  return token.toUpperCase() === 'TRX' || token === context.chain.contracts.trx\n}\n\nexport function evmHexToTronAddress(address: string, label = 'address'): TronAddress {\n  const normalized = address.startsWith('0x') ? address.toLowerCase() : `0x${address.toLowerCase()}`\n  return evmHexToTronAddressV2(normalized, label)\n}\n\nexport function tronAddressToEvmAddress(address: TronAddress | string, label = 'address'): `0x${string}` {\n  return `0x${tronAddressToEvmHex(assertTronAddress(address, label))}`\n}\n\n/** Canonical address for comparing configured tokens with decoded contract results. */\nexport function normalizeTronAddress(address: string, label = 'address'): TronAddress {\n  if (/^41[0-9a-fA-F]{40}$/.test(address)) return evmHexToTronAddress(`0x${address.slice(2)}`, label)\n  if (/^0x[0-9a-fA-F]{40}$/.test(address)) return evmHexToTronAddress(address, label)\n  return evmHexToTronAddress(tronAddressToEvmAddress(address, label), label)\n}\n\nexport function normalizeProtocolToken(\n  context: ProtocolsContext,\n  token: string,\n  label: string,\n  metadata: { readonly decimals?: number; readonly symbol?: string; readonly name?: string } = {},\n): ProtocolToken {\n  const wrappedContractAddress = getWrappedNativeAddress(context.network)\n  const kind: ProtocolTokenKind = isNativeTrxInput(context, token) ? 'native' : 'token'\n  const contractAddress = kind === 'native' ? TRON_ZERO_ADDRESS : assertTronAddress(token, label)\n  const mathAddress = kind === 'native' ? wrappedContractAddress : contractAddress\n  const evmAddress = `0x${tronAddressToEvmHex(mathAddress)}`.toLowerCase()\n\n  return {\n    kind,\n    input: token,\n    contractAddress,\n    wrappedContractAddress,\n    token: new Token(\n      context.chain.uniswapChainId,\n      evmAddress,\n      metadata.decimals ?? 6,\n      metadata.symbol,\n      metadata.name,\n      true,\n    ),\n  }\n}\n\nfunction parseLiquidityPercentageInput(value: SlippageInput | Percent, label: string): Percent {\n  if (value instanceof Percent) return value\n\n  const match = PERCENT_PATTERN.exec(value)\n  if (!match) {\n    throw new SDKError('SDK_INVALID_ARGUMENT', `${label} must be a percentage string`, {\n      label,\n      percentage: value,\n    })\n  }\n\n  const whole = match[1] ?? '0'\n  const fraction = match[2] ?? ''\n  const scale = 10n ** BigInt(fraction.length)\n  const percentageUnits = BigInt(whole) * scale + BigInt(fraction || '0')\n  return new Percent(percentageUnits.toString(), (100n * scale).toString())\n}\n\nexport function normalizeLiquidityPercentage(value: SlippageInput | Percent, label: string): Percent {\n  const percent = parseLiquidityPercentageInput(value, label)\n  if (percent.equalTo(0)) {\n    throw new SDKError('SDK_INVALID_ARGUMENT', `${label} must be greater than 0%`, {\n      label,\n      percentage: percent.toSignificant(),\n    })\n  }\n  if (percent.greaterThan(1)) {\n    throw new SDKError('SDK_INVALID_ARGUMENT', `${label} must be at most 100%`, {\n      label,\n      percentage: percent.toSignificant(),\n    })\n  }\n  return percent\n}\n"],"mappings":"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","names":["SDKError","SDKError","SDKError"]}