@tonappchain/sdk 0.7.0-rc8 → 0.7.0

package/dist/src/agnosticSdk/AgnosticSdk.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgnosticProxySDK = void 0;
+const mainnet_1 = require("../../artifacts/mainnet");
+const testnet_1 = require("../../artifacts/testnet");
+const Struct_1 = require("../structs/Struct");
+const AbiHandler_1 = require("./AbiHandler");
+const DebugHelpers_1 = require("./DebugHelpers");
+const HooksHandler_1 = require("./HooksHandler");
+const ReplacementHelper_1 = require("./ReplacementHelper");
+/**
+ * SDK for building AgnosticProxy Zap calls with efficient hook encoding
+ * @param network - The network to use (MAINNET || TESTNET || DEV)
+ * @param agnosticProxyAddress - The address of the agnostic proxy(optional)
+ */
+class AgnosticProxySDK {
+    constructor(network, agnosticProxyAddress) {
+        switch (network) {
+            case Struct_1.Network.MAINNET:
+                this.agnosticProxyAddress = agnosticProxyAddress ?? mainnet_1.AGNOSTIC_PROXY_ADDRESS;
+                break;
+            case Struct_1.Network.TESTNET:
+                this.agnosticProxyAddress = agnosticProxyAddress ?? testnet_1.AGNOSTIC_PROXY_ADDRESS;
+                break;
+            case Struct_1.Network.DEV:
+                if (!agnosticProxyAddress) {
+                    throw new Error('Agnostic proxy address is required for dev network');
+                }
+                this.agnosticProxyAddress = agnosticProxyAddress;
+                break;
+        }
+        this.abiHandler = new AbiHandler_1.AbiHandler();
+        this.replacementHelper = new ReplacementHelper_1.ReplacementHelper();
+        this.hooksHandler = new HooksHandler_1.HooksHandler();
+        this.debugHelpers = new DebugHelpers_1.DebugHelpers();
+    }
+    addContractInterface(address, abi) {
+        this.abiHandler.addContractInterface(address, abi);
+        return this;
+    }
+    /**
+     * Create a custom hook with optional dynamic value replacement
+     * @param contractAddress - The address of the contract to call
+     * @param functionName - The name of the function to call
+     * @param params - The parameters of the function to call
+     * @param options - The options of the custom hook
+     * @returns The custom hook
+     */
+    createCustomHook(contractAddress, functionName, params, options = {}) {
+        return this.hooksHandler.createCustomHook(contractAddress, functionName, params, this.abiHandler.contractInterfaces, options);
+    }
+    /**
+     * Create a full balance approve hook
+     * @param token - The token to approve
+     * @param to - The address to approve to
+     * @param isFromSAPerspective - Whether the hook is from the smart account perspective or from proxy perspective
+     * @returns The full balance approve hook
+     */
+    createFullBalanceApproveHook(token, to, isFromSAPerspective = true) {
+        return this.hooksHandler.createFullBalanceApproveHook(token, to, isFromSAPerspective);
+    }
+    /**
+     * Create a full balance transfer hook
+     * @param token - The token to transfer
+     * @param to - The address to transfer to
+     * @param isFromSAPerspective - Whether the hook is from the smart account perspective or from proxy perspective
+     * @returns The full balance transfer hook
+     */
+    createFullBalanceTransferHook(token, to, isFromSAPerspective = true) {
+        return this.hooksHandler.createFullBalanceTransferHook(token, to, isFromSAPerspective);
+    }
+    /**
+     * Utility: Create multiple approve hooks at once
+     * @param approvals - The approvals to create
+     * @returns The multiple approve hooks
+     */
+    createMultipleApproves(approvals) {
+        return this.hooksHandler.createMultipleApproves(approvals);
+    }
+    /**
+     * Utility: Create a sequence of custom hooks
+     * @param calls - The calls to create
+     * @returns The hook sequence
+     */
+    createHookSequence(calls) {
+        return calls.map((call) => this.createCustomHook(call.contract, call.functionName, call.params, call.options));
+    }
+    /**
+     * Helper to create dynamic amount replacement for a specific parameter
+     * @param paramIndex - The index of the parameter to replace
+     * @param token - The token to replace
+     * @param balanceAddress - The address to replace the parameter with
+     * @returns The amount replacement
+     */
+    createAmountReplacement(paramIndex, token, balanceAddress) {
+        return this.replacementHelper.createAmountReplacement(paramIndex, token, balanceAddress);
+    }
+    /**
+     * Advanced replacement calculator - calculates position and length for any parameter type
+     * Required that you have added the contract interface first using addContractInterface().
+     * If human readable abi is used, need to provide function and params names also
+     * @param contractAddress - The address of the contract to call
+     * @param functionName - The name of the function to call
+     * @param parameterName - The name of the parameter to replace
+     * @param token - The token to replace
+     * @param balanceAddress - The address to replace the parameter with
+     * @returns The replacement data
+     */
+    calculateReplacementData(contractAddress, functionName, parameterName, token, balanceAddress) {
+        return this.replacementHelper.calculateReplacementData(contractAddress, functionName, parameterName, token, balanceAddress, this.abiHandler.contractInterfaces);
+    }
+    /**
+     * Get replacement helper - shows available functions and parameters for a contract
+     * Required that you have added the contract interface first using addContractInterface().
+     * If human readable abi is used, need to provide function and params names also
+     * @param contractAddress - The address of the contract to call
+     * @returns The replacement helper
+     */
+    getReplacementHelper(contractAddress) {
+        return this.replacementHelper.getReplacementHelper(contractAddress, this.abiHandler.contractInterfaces);
+    }
+    /**
+     * Interactive replacement builder - helps build replacement step by step
+     * @param contractAddress - The address of the contract to call
+     * @param functionName - The name of the function to call
+     * @param parameterName - The name of the parameter to replace
+     * @param token - The token to replace
+     * @param balanceAddress - The address to replace the parameter with
+     * @param options - The options of the interactive replacement builder
+     * @returns The interactive replacement builder
+     */
+    buildReplacementInteractive(contractAddress, functionName, parameterName, token, balanceAddress, options = {}) {
+        return this.replacementHelper.buildReplacementInteractive(contractAddress, functionName, parameterName, token, balanceAddress, this.abiHandler.contractInterfaces, options);
+    }
+    /**
+     * Debug helper: Decode hook data back to readable format
+     * @param hook - The hook to decode
+     * @returns The decoded hook
+     */
+    decodeHookData(hook) {
+        return this.debugHelpers.decodeHookData(hook);
+    }
+    /**
+     * Debug helper: Get estimated gas for a ZapCall
+     * @param zapCall - The zap call to estimate the gas usage for
+     * @returns The estimated gas usage
+     */
+    estimateGasUsage(zapCall) {
+        return this.debugHelpers.estimateGasUsage(zapCall);
+    }
+    /**
+     * Visualize ZapCall chain - Human readable description of all operations
+     * @param zapCall - The zap call to visualize
+     */
+    visualizeZapCall(zapCall) {
+        return this.debugHelpers.visualizeZapCall(zapCall, this.abiHandler.contractInterfaces);
+    }
+    /**
+     * Get a detailed breakdown of a ZapCall for logging
+     * @param zapCall - The zap call to get the breakdown for
+     * @returns The breakdown of the zap call
+     */
+    getZapCallBreakdown(zapCall) {
+        return this.debugHelpers.getZapCallBreakdown(zapCall, this.abiHandler.contractInterfaces);
+    }
+    /**
+     * Compare two ZapCalls and show differences
+     * @param zapCall1 - The first zap call to compare
+     * @param zapCall2 - The second zap call to compare
+     * @param label1 - The label of the first zap call
+     * @param label2 - The label of the second zap call
+     */
+    compareZapCalls(zapCall1, zapCall2, label1 = 'ZapCall 1', label2 = 'ZapCall 2') {
+        return this.debugHelpers.compareZapCalls(zapCall1, zapCall2, label1, label2, this.abiHandler.contractInterfaces);
+    }
+    getAgnosticCallParams() {
+        return {
+            evmTargetAddress: this.agnosticProxyAddress,
+            methodName: 'Zap(bytes,bytes)',
+        };
+    }
+    /**
+     * Build a complete ZapCall
+     * @param hooks - The hooks of the zap call
+     * @param bridgeTokens - The tokens to bridge
+     * @param bridgeNFTs - The nfts to bridge
+     * @returns The zap call
+     */
+    buildZapCall(hooks, bridgeTokens = [], bridgeNFTs = []) {
+        return this.debugHelpers.buildZapCall(hooks, bridgeTokens, bridgeNFTs);
+    }
+    /**
+     * Encode ZapCall for transaction
+     * @param zapCall - The zap call to encode
+     * @returns The encoded zap call that can be used as calldata in tac sdk
+     */
+    encodeZapCall(zapCall) {
+        return this.debugHelpers.encodeZapCall(zapCall);
+    }
+}
+exports.AgnosticProxySDK = AgnosticProxySDK;

package/dist/src/agnosticSdk/AgnosticStructs.d.ts

@@ -0,0 +1,108 @@
+/**
+ * NFTData is a struct that contains the nft, id, and amount of the nft
+ * @param nft - The address of the nft
+ * @param id - The id of the nft
+ * @param amount - The amount of the nft to transfer(for ERC1155, but currently supported only ERC721)
+ */
+export interface NFTData {
+    nft: string;
+    id: bigint;
+    amount: bigint;
+}
+/**
+ * BridgeData is a struct that contains the tokens, nfts, and isRequired of the bridge data
+ * @param tokens - The addresses of the tokens to bridge
+ * @param nfts - The nfts to bridge
+ * @param isRequired - Whether the bridge is required
+ */
+export interface BridgeData {
+    tokens: string[];
+    nfts: NFTData[];
+    isRequired: boolean;
+}
+/**
+ * HookType is an enum that contains the type of the hook
+ * @param Custom - The custom hook
+ * @param FullBalanceApprove - The full balance approve hook
+ * @param FullBalanceTransfer - The full balance transfer hook
+ */
+export declare enum HookType {
+    Custom = 0,
+    FullBalanceApprove = 1,
+    FullBalanceTransfer = 2
+}
+/**
+ * ReplacementType is an enum that contains the type of the replacement
+ * @param Amount - The amount replacement
+ */
+export declare enum ReplacementType {
+    Amount = 0
+}
+/**
+ * AmountChange is a struct that contains the position, length, token, and balance address of the amount change
+ * @param position - The position of the amount change(position of the parameter in the function call)
+ * @param len - The length of the amount change(length of the parameter in the function call)
+ * @param token - The token of the amount change
+ * @param balanceAddress - The balance address of the amount change(address to check balance for)
+ */
+export interface AmountChange {
+    position: number;
+    len: number;
+    token: string;
+    balanceAddress: string;
+}
+/**
+ * CustomHookData is a struct that contains the isFromSAPerspective, contractAddress, value, data, and improvedMissionInfo of the custom hook
+ * @param isFromSAPerspective - Whether the hook is from the smart account perspective or from proxy perspective
+ * @param contractAddress - The address of the contract to call
+ * @param value - The value of the hook
+ * @param data - The data of the hook
+ * @param improvedMissionInfo - The improved mission info of the hook
+ */
+export interface CustomHookData {
+    isFromSAPerspective: boolean;
+    contractAddress: string;
+    value: bigint;
+    data: string;
+    improvedMissionInfo: string;
+}
+/**
+ * ApproveHookData is a struct that contains the token, to, and isFromSAPerspective of the approve hook
+ * @param token - The token to approve
+ * @param to - The address to approve to
+ * @param isFromSAPerspective - Whether the hook is from the smart account perspective or from proxy perspective
+ */
+export interface ApproveHookData {
+    token: string;
+    to: string;
+    isFromSAPerspective: boolean;
+}
+/**
+ * TransferHookData is a struct that contains the token, to, and isFromSAPerspective of the transfer hook
+ * @param token - The token to transfer
+ * @param to - The address to transfer to
+ * @param isFromSAPerspective - Whether the hook is from the smart account perspective or from proxy perspective
+ */
+export interface TransferHookData {
+    token: string;
+    to: string;
+    isFromSAPerspective: boolean;
+}
+/**
+ * Hook is a struct that contains the hookType and hookData of the hook
+ * @param hookType - The type of the hook
+ * @param hookData - The data of the hook
+ */
+export interface Hook {
+    hookType: HookType;
+    hookData: string;
+}
+/**
+ * ZapCall is a struct that contains the hooks and bridgeData of the zap call
+ * @param hooks - The hooks of the zap call
+ * @param bridgeData - The bridge data of the zap call
+ */
+export interface ZapCall {
+    hooks: Hook[];
+    bridgeData: BridgeData;
+}

package/dist/src/agnosticSdk/AgnosticStructs.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReplacementType = exports.HookType = void 0;
+/**
+ * HookType is an enum that contains the type of the hook
+ * @param Custom - The custom hook
+ * @param FullBalanceApprove - The full balance approve hook
+ * @param FullBalanceTransfer - The full balance transfer hook
+ */
+var HookType;
+(function (HookType) {
+    HookType[HookType["Custom"] = 0] = "Custom";
+    HookType[HookType["FullBalanceApprove"] = 1] = "FullBalanceApprove";
+    HookType[HookType["FullBalanceTransfer"] = 2] = "FullBalanceTransfer";
+})(HookType || (exports.HookType = HookType = {}));
+/**
+ * ReplacementType is an enum that contains the type of the replacement
+ * @param Amount - The amount replacement
+ */
+var ReplacementType;
+(function (ReplacementType) {
+    ReplacementType[ReplacementType["Amount"] = 0] = "Amount";
+})(ReplacementType || (exports.ReplacementType = ReplacementType = {}));

package/dist/src/agnosticSdk/DebugHelpers.d.ts

@@ -0,0 +1,88 @@
+import { Interface } from 'ethers';
+import { Hook, NFTData, ZapCall } from './AgnosticStructs';
+export declare class DebugHelpers {
+    /**
+     * Build a complete ZapCall
+     * @param hooks - The hooks of the zap call
+     * @param bridgeTokens - The tokens to bridge
+     * @param bridgeNFTs - The nfts to bridge
+     * @returns The zap call
+     */
+    buildZapCall(hooks: Hook[], bridgeTokens?: string[], bridgeNFTs?: NFTData[]): ZapCall;
+    /**
+     * Debug helper: Decode hook data back to readable format
+     * @param hook - The hook to decode
+     * @returns The decoded hook
+     */
+    decodeHookData(hook: Hook): any;
+    /**
+     * Debug helper: Get estimated gas for a ZapCall
+     * @param zapCall - The zap call to estimate the gas usage for
+     * @returns The estimated gas usage
+     */
+    estimateGasUsage(zapCall: ZapCall): number;
+    /**
+     * Visualize ZapCall chain - Human readable description of all operations
+     * @param zapCall - The zap call to visualize
+     */
+    visualizeZapCall(zapCall: ZapCall, contractInterfaces: Map<string, Interface>): void;
+    /**
+     * Private helper to describe individual hooks
+     * @param hook - The hook to describe
+     * @returns The description of the hook
+     */
+    private _describeHook;
+    /**
+     * Describe custom hook with function details
+     * @param hook - The hook to describe
+     * @returns The description of the hook
+     */
+    private _describeCustomHook;
+    /**
+     * Describe approve hook
+     * @param hook - The hook to describe
+     * @returns The description of the hook
+     */
+    private _describeApproveHook;
+    /**
+     * Describe transfer hook
+     * @param hook - The hook to describe
+     * @returns The description of the hook
+     */
+    private _describeTransferHook;
+    /**
+     * Format address for display (show first 6 and last 4 characters)
+     * @param address - The address to format
+     * @returns The formatted address
+     */
+    private _formatAddress;
+    /**
+     * Get a detailed breakdown of a ZapCall for logging
+     * @param zapCall - The zap call to get the breakdown for
+     * @returns The breakdown of the zap call
+     */
+    getZapCallBreakdown(zapCall: ZapCall, contractInterfaces: Map<string, Interface>): {
+        totalHooks: number;
+        hookTypes: {
+            [key: string]: number;
+        };
+        gasEstimate: number;
+        encodedSize: number;
+        bridgeRequired: boolean;
+        hookDescriptions: string[];
+    };
+    /**
+     * Compare two ZapCalls and show differences
+     * @param zapCall1 - The first zap call to compare
+     * @param zapCall2 - The second zap call to compare
+     * @param label1 - The label of the first zap call
+     * @param label2 - The label of the second zap call
+     */
+    compareZapCalls(zapCall1: ZapCall, zapCall2: ZapCall, label1: string | undefined, label2: string | undefined, contractInterfaces: Map<string, Interface>): void;
+    /**
+     * Encode ZapCall for transaction
+     * @param zapCall - The zap call to encode
+     * @returns The encoded zap call that can be used as calldata in tac sdk
+     */
+    encodeZapCall(zapCall: ZapCall): string;
+}