@tonappchain/sdk 0.7.0-rc17 → 0.7.0-rc19

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

@@ -0,0 +1,371 @@
+import { Network } from "../structs/Struct";
+/**
+ * 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;
+}
+/**
+ * SDK for building AgnosticProxy Zap calls with efficient hook encoding
+ * @param agnosticProxyAddress - The address of the agnostic proxy(optional)
+ */
+export declare class AgnosticProxySDK {
+    private contractInterfaces;
+    private agnosticProxyAddress;
+    constructor(network: Network, agnosticProxyAddress?: string);
+    /**
+     * Add a contract interface for encoding function calls
+     * Supports both human-readable ABI strings and generated ABI JSON objects
+     * @param address - The address of the contract to add interface for
+     * @param abi - The abi of the contract to add interface for
+     * @returns The sdk instance
+     */
+    addContractInterface(address: string, abi: any[]): this;
+    /**
+     * Parse ABI - handles both human-readable strings and generated ABI JSON objects
+     * Extracts only function definitions from JSON ABI
+     */
+    private _parseAbi;
+    /**
+     * Build human-readable function signature from JSON ABI function object
+     * @param func - The function to build signature for
+     * @returns The signature of the function
+     */
+    private _buildFunctionSignature;
+    /**
+     * 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: string, functionName: string, params: any[], options?: {
+        isFromSAPerspective?: boolean;
+        value?: bigint;
+        dynamicReplacements?: AmountChange[];
+    }): Hook;
+    /**
+     * 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: string, to: string, isFromSAPerspective?: boolean): Hook;
+    /**
+     * 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: string, to: string, isFromSAPerspective?: boolean): Hook;
+    /**
+     * 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: number, token: string, balanceAddress: string): AmountChange;
+    /**
+     * 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: string, functionName: string, parameterName: string, token: string, balanceAddress: string): AmountChange;
+    /**
+     * 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: string): {
+        contractAddress: string;
+        functions: {
+            name: string;
+            signature: string;
+            parameters: {
+                name: string;
+                type: string;
+                index: number;
+                canReplace: boolean;
+                reason?: string;
+            }[];
+        }[];
+    };
+    /**
+     * 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: string, functionName: string, parameterName: string, token: string, balanceAddress: string, options?: {
+        showCalculation?: boolean;
+        validate?: boolean;
+    }): {
+        replacement: AmountChange;
+        calculation: {
+            functionSignature: string;
+            parameterInfo: {
+                name: string;
+                type: string;
+                index: number;
+                position: number;
+                length: number;
+            };
+            positionCalculation: string;
+        };
+        validation: {
+            isValid: boolean;
+            warnings: string[];
+            suggestions: string[];
+        };
+    };
+    /**
+     * Private helper to calculate position and length for complex parameter types
+     * @param inputs - The inputs of the function
+     * @param targetIndex - The index of the parameter to calculate the position and length for
+     * @returns The position and length of the parameter
+     */
+    private _calculateParamPositionAndLength;
+    /**
+     * Get the size in bytes for a parameter type
+     * @param type - The type of the parameter
+     * @returns The size in bytes of the parameter
+     */
+    private _getTypeSize;
+    /**
+     * Check if a parameter type can be replaced with a balance
+     * @param type - The type of the parameter
+     * @returns The can replace and reason of the parameter
+     */
+    private _canParameterBeReplaced;
+    /**
+     * 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;
+    /**
+     * Encode ZapCall for transaction - Much more efficient now!
+     * @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;
+    /**
+     * Utility: Create multiple approve hooks at once
+     * @param approvals - The approvals to create
+     * @returns The multiple approve hooks
+     */
+    createMultipleApproves(approvals: {
+        token: string;
+        spender: string;
+        isFromSA?: boolean;
+    }[]): Hook[];
+    /**
+     * Utility: Create a sequence of custom hooks
+     * @param calls - The calls to create
+     * @returns The hook sequence
+     */
+    createHookSequence(calls: {
+        contract: string;
+        functionName: string;
+        params: any[];
+        options?: {
+            isFromSAPerspective?: boolean;
+            value?: bigint;
+            dynamicReplacements?: AmountChange[];
+        };
+    }[]): Hook[];
+    /**
+     * 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): 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): {
+        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, label2?: string): void;
+    getAgnosticCallParams(): {
+        evmTargetAddress: string;
+        methodName: string;
+    };
+}