@tonappchain/sdk 0.7.0-rc9 → 0.7.1

package/dist/src/agnosticSdk/DebugHelpers.js

@@ -0,0 +1,274 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DebugHelpers = void 0;
+const ethers_1 = require("ethers");
+const AgnosticStructs_1 = require("./AgnosticStructs");
+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, bridgeTokens = [], bridgeNFTs = []) {
+        return {
+            hooks,
+            bridgeData: {
+                tokens: bridgeTokens,
+                nfts: bridgeNFTs,
+                isRequired: bridgeTokens.length > 0 || bridgeNFTs.length > 0,
+            },
+        };
+    }
+    /**
+     * Debug helper: Decode hook data back to readable format
+     * @param hook - The hook to decode
+     * @returns The decoded hook
+     */
+    decodeHookData(hook) {
+        try {
+            switch (hook.hookType) {
+                case AgnosticStructs_1.HookType.Custom:
+                    return ethers_1.ethers.AbiCoder.defaultAbiCoder().decode(['tuple(bool,address,uint256,bytes,bytes)'], hook.hookData)[0];
+                case AgnosticStructs_1.HookType.FullBalanceApprove:
+                    return ethers_1.ethers.AbiCoder.defaultAbiCoder().decode(['tuple(address,address,bool)'], hook.hookData)[0];
+                case AgnosticStructs_1.HookType.FullBalanceTransfer:
+                    return ethers_1.ethers.AbiCoder.defaultAbiCoder().decode(['tuple(address,address,bool)'], hook.hookData)[0];
+                default:
+                    throw new Error(`Unknown hook type: ${hook.hookType}`);
+            }
+        }
+        catch (error) {
+            throw new Error(`Failed to decode hook data: ${error}`);
+        }
+    }
+    /**
+     * 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) {
+        // Rough estimation based on hook types and operations
+        let gasEstimate = 50000; // Base gas
+        zapCall.hooks.forEach((hook) => {
+            switch (hook.hookType) {
+                case AgnosticStructs_1.HookType.Custom:
+                    gasEstimate += 100000; // Custom calls can vary widely
+                    break;
+                case AgnosticStructs_1.HookType.FullBalanceApprove:
+                    gasEstimate += 50000; // ERC20 approve
+                    break;
+                case AgnosticStructs_1.HookType.FullBalanceTransfer:
+                    gasEstimate += 65000; // ERC20 transfer
+                    break;
+            }
+        });
+        if (zapCall.bridgeData.isRequired) {
+            gasEstimate += 200000; // Bridge operations
+        }
+        return gasEstimate;
+    }
+    /**
+     * Visualize ZapCall chain - Human readable description of all operations
+     * @param zapCall - The zap call to visualize
+     */
+    visualizeZapCall(zapCall, contractInterfaces) {
+        console.log('🔗 ZapCall Chain Visualization');
+        console.log('================================');
+        if (zapCall.hooks.length === 0) {
+            console.log('❌ No hooks in this ZapCall');
+            return;
+        }
+        zapCall.hooks.forEach((hook, index) => {
+            const stepNumber = (index + 1).toString().padStart(2, ' ');
+            console.log(`\n${stepNumber}. ${this._describeHook(hook, contractInterfaces)}`);
+        });
+        // Bridge information
+        if (zapCall.bridgeData.isRequired) {
+            console.log('\n🌉 Bridge Operations:');
+            if (zapCall.bridgeData.tokens.length > 0) {
+                console.log(`   📤 Bridge tokens: ${zapCall.bridgeData.tokens.map((t) => this._formatAddress(t)).join(', ')}`);
+            }
+            if (zapCall.bridgeData.nfts.length > 0) {
+                console.log(`   🖼️  Bridge NFTs: ${zapCall.bridgeData.nfts.length} NFT(s)`);
+                zapCall.bridgeData.nfts.forEach((nft, i) => {
+                    console.log(`      ${i + 1}. ${this._formatAddress(nft.nft)} #${nft.id} (amount: ${nft.amount})`);
+                });
+            }
+        }
+        else {
+            console.log('\n🚫 No bridge operations required');
+        }
+        // Summary
+        console.log('\n📊 Summary:');
+        console.log(`   Total hooks: ${zapCall.hooks.length}`);
+        console.log(`   Estimated gas: ${this.estimateGasUsage(zapCall).toLocaleString()}`);
+        console.log(`   Bridge required: ${zapCall.bridgeData.isRequired ? 'Yes' : 'No'}`);
+        console.log('================================');
+    }
+    /**
+     * Private helper to describe individual hooks
+     * @param hook - The hook to describe
+     * @returns The description of the hook
+     */
+    _describeHook(hook, contractInterfaces) {
+        try {
+            switch (hook.hookType) {
+                case AgnosticStructs_1.HookType.Custom:
+                    return this._describeCustomHook(hook, contractInterfaces);
+                case AgnosticStructs_1.HookType.FullBalanceApprove:
+                    return this._describeApproveHook(hook);
+                case AgnosticStructs_1.HookType.FullBalanceTransfer:
+                    return this._describeTransferHook(hook);
+                default:
+                    return `❓ Unknown hook type: ${hook.hookType}`;
+            }
+        }
+        catch (error) {
+            return `❌ Error describing hook: ${error}`;
+        }
+    }
+    /**
+     * Describe custom hook with function details
+     * @param hook - The hook to describe
+     * @returns The description of the hook
+     */
+    _describeCustomHook(hook, contractInterfaces) {
+        const decoded = this.decodeHookData(hook);
+        const [isFromSA, contractAddress, value, data, improvedMissionInfo] = decoded;
+        // Try to decode function name from data
+        let functionDescription = 'unknown function';
+        let hasReplacements = false;
+        if (data && data.length >= 10) {
+            // At least 4 bytes for selector + some data
+            const selector = data.slice(0, 10); // "0x" + 8 hex chars
+            // Try to find function name from registered interfaces
+            for (const [address, contractInterface] of contractInterfaces) {
+                if (address === contractAddress.toLowerCase()) {
+                    try {
+                        const fragment = contractInterface.getFunction(selector);
+                        if (fragment) {
+                            functionDescription = `${fragment.name}(${fragment.inputs.map((input) => input.type).join(', ')})`;
+                            break;
+                        }
+                    }
+                    catch {
+                        // Function not found in this interface
+                    }
+                }
+            }
+            // If not found in registered interfaces, just show selector
+            if (functionDescription === 'unknown function') {
+                functionDescription = `function with selector ${selector}`;
+            }
+        }
+        // Check for dynamic replacements
+        if (improvedMissionInfo && improvedMissionInfo !== '0x' && improvedMissionInfo.length > 2) {
+            hasReplacements = true;
+        }
+        const perspective = isFromSA ? 'Smart Account' : 'Proxy Contract';
+        const valueStr = value > 0n ? ` (sending ${ethers_1.ethers.formatEther(value)} ETH)` : '';
+        const replacementStr = hasReplacements ? ' 🔄 [with dynamic value replacement]' : '';
+        return `📞 Custom call to ${this._formatAddress(contractAddress)} from ${perspective}${valueStr}
+     Function: ${functionDescription}${replacementStr}`;
+    }
+    /**
+     * Describe approve hook
+     * @param hook - The hook to describe
+     * @returns The description of the hook
+     */
+    _describeApproveHook(hook) {
+        const decoded = this.decodeHookData(hook);
+        const [token, to, isFromSA] = decoded;
+        const perspective = isFromSA ? 'Smart Account' : 'Proxy Contract';
+        return `✅ Approve full balance of ${this._formatAddress(token)} to ${this._formatAddress(to)} from ${perspective}`;
+    }
+    /**
+     * Describe transfer hook
+     * @param hook - The hook to describe
+     * @returns The description of the hook
+     */
+    _describeTransferHook(hook) {
+        const decoded = this.decodeHookData(hook);
+        const [token, to, isFromSA] = decoded;
+        const perspective = isFromSA ? 'Smart Account' : 'Proxy Contract';
+        return `💸 Transfer full balance of ${this._formatAddress(token)} to ${this._formatAddress(to)} from ${perspective}`;
+    }
+    /**
+     * Format address for display (show first 6 and last 4 characters)
+     * @param address - The address to format
+     * @returns The formatted address
+     */
+    _formatAddress(address) {
+        if (!address || address.length < 10)
+            return address;
+        return `${address.slice(0, 6)}...${address.slice(-4)}`;
+    }
+    /**
+     * 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, contractInterfaces) {
+        const hookTypes = {};
+        const hookDescriptions = [];
+        zapCall.hooks.forEach((hook, index) => {
+            const typeName = AgnosticStructs_1.HookType[hook.hookType];
+            hookTypes[typeName] = (hookTypes[typeName] || 0) + 1;
+            hookDescriptions.push(`${index + 1}. ${this._describeHook(hook, contractInterfaces)}`);
+        });
+        return {
+            totalHooks: zapCall.hooks.length,
+            hookTypes,
+            gasEstimate: this.estimateGasUsage(zapCall),
+            encodedSize: this.encodeZapCall(zapCall).length / 2, // bytes
+            bridgeRequired: zapCall.bridgeData.isRequired,
+            hookDescriptions,
+        };
+    }
+    /**
+     * 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', contractInterfaces) {
+        console.log(`🔄 Comparing ${label1} vs ${label2}`);
+        console.log('='.repeat(50));
+        const breakdown1 = this.getZapCallBreakdown(zapCall1, contractInterfaces);
+        const breakdown2 = this.getZapCallBreakdown(zapCall2, contractInterfaces);
+        console.log(`📊 ${label1}:`);
+        console.log(`   Hooks: ${breakdown1.totalHooks}, Gas: ${breakdown1.gasEstimate.toLocaleString()}, Size: ${breakdown1.encodedSize} bytes`);
+        console.log(`📊 ${label2}:`);
+        console.log(`   Hooks: ${breakdown2.totalHooks}, Gas: ${breakdown2.gasEstimate.toLocaleString()}, Size: ${breakdown2.encodedSize} bytes`);
+        console.log('\n📈 Differences:');
+        console.log(`   Hooks: ${breakdown2.totalHooks - breakdown1.totalHooks > 0 ? '+' : ''}${breakdown2.totalHooks - breakdown1.totalHooks}`);
+        console.log(`   Gas: ${breakdown2.gasEstimate - breakdown1.gasEstimate > 0 ? '+' : ''}${(breakdown2.gasEstimate - breakdown1.gasEstimate).toLocaleString()}`);
+        console.log(`   Size: ${breakdown2.encodedSize - breakdown1.encodedSize > 0 ? '+' : ''}${breakdown2.encodedSize - breakdown1.encodedSize} bytes`);
+    }
+    /**
+     * 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 ethers_1.ethers.AbiCoder.defaultAbiCoder().encode([
+            'tuple(' +
+                'tuple(uint8,bytes)[],' + // hooks: only hookType and hookData
+                'tuple(address[],tuple(address,uint256,uint256)[],bool)' + // bridgeData
+                ')',
+        ], [
+            [
+                zapCall.hooks.map((hook) => [hook.hookType, hook.hookData]),
+                [
+                    zapCall.bridgeData.tokens,
+                    zapCall.bridgeData.nfts.map((nft) => [nft.nft, nft.id, nft.amount]),
+                    zapCall.bridgeData.isRequired,
+                ],
+            ],
+        ]);
+    }
+}
+exports.DebugHelpers = DebugHelpers;

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

@@ -0,0 +1,43 @@
+import { Interface } from 'ethers';
+import { AmountChange, Hook } from './AgnosticStructs';
+export declare class HooksHandler {
+    /**
+     * 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[], contractInterfaces: Map<string, Interface>, 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;
+    /**
+     * 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[];
+}

package/dist/src/agnosticSdk/HooksHandler.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HooksHandler = void 0;
+const ethers_1 = require("ethers");
+const AgnosticStructs_1 = require("./AgnosticStructs");
+class HooksHandler {
+    /**
+     * 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, contractInterfaces, options = {}) {
+        const { isFromSAPerspective = true, value = 0n, dynamicReplacements } = options;
+        const contractInterface = contractInterfaces.get(contractAddress.toLowerCase());
+        if (!contractInterface) {
+            throw new Error(`Contract interface not found for address: ${contractAddress}`);
+        }
+        const data = contractInterface.encodeFunctionData(functionName, params);
+        let improvedMissionInfo = '0x';
+        // If dynamic replacements are specified, encode them
+        if (dynamicReplacements && dynamicReplacements.length > 0) {
+            // For now, support single replacement (can be extended)
+            const replacement = dynamicReplacements[0];
+            const replacementData = ethers_1.ethers.AbiCoder.defaultAbiCoder().encode(['tuple(uint16,uint16,address,address)'], [[replacement.position, replacement.len, replacement.token, replacement.balanceAddress]]);
+            // Encode as ReplacementType.Amount with the replacement data
+            improvedMissionInfo = ethers_1.ethers.AbiCoder.defaultAbiCoder().encode(['uint8', 'bytes'], [AgnosticStructs_1.ReplacementType.Amount, replacementData]);
+        }
+        const customHookData = {
+            isFromSAPerspective,
+            contractAddress: ethers_1.ethers.getAddress(contractAddress.toLowerCase()), // Normalize address to checksum format
+            value,
+            data,
+            improvedMissionInfo,
+        };
+        // Encode only the CustomHookData
+        const encodedHookData = ethers_1.ethers.AbiCoder.defaultAbiCoder().encode(['tuple(bool,address,uint256,bytes,bytes)'], [
+            [
+                customHookData.isFromSAPerspective,
+                customHookData.contractAddress,
+                customHookData.value,
+                customHookData.data,
+                customHookData.improvedMissionInfo,
+            ],
+        ]);
+        return {
+            hookType: AgnosticStructs_1.HookType.Custom,
+            hookData: encodedHookData,
+        };
+    }
+    /**
+     * 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) {
+        const approveHookData = {
+            token,
+            to,
+            isFromSAPerspective,
+        };
+        // Encode only the ApproveHookData
+        const encodedHookData = ethers_1.ethers.AbiCoder.defaultAbiCoder().encode(['tuple(address,address,bool)'], [[approveHookData.token, approveHookData.to, approveHookData.isFromSAPerspective]]);
+        return {
+            hookType: AgnosticStructs_1.HookType.FullBalanceApprove,
+            hookData: encodedHookData,
+        };
+    }
+    /**
+     * 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) {
+        const transferHookData = {
+            token,
+            to,
+            isFromSAPerspective,
+        };
+        // Encode only the TransferHookData
+        const encodedHookData = ethers_1.ethers.AbiCoder.defaultAbiCoder().encode(['tuple(address,address,bool)'], [[transferHookData.token, transferHookData.to, transferHookData.isFromSAPerspective]]);
+        return {
+            hookType: AgnosticStructs_1.HookType.FullBalanceTransfer,
+            hookData: encodedHookData,
+        };
+    }
+    /**
+     * Utility: Create multiple approve hooks at once
+     * @param approvals - The approvals to create
+     * @returns The multiple approve hooks
+     */
+    createMultipleApproves(approvals) {
+        return approvals.map((approval) => this.createFullBalanceApproveHook(approval.token, approval.spender, approval.isFromSA ?? true));
+    }
+}
+exports.HooksHandler = HooksHandler;

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

@@ -0,0 +1,95 @@
+import { Interface } from 'ethers';
+import { AmountChange } from './AgnosticStructs';
+export declare class ReplacementHelper {
+    /**
+     * 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, contractInterfaces: Map<string, Interface>): 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, contractInterfaces: Map<string, Interface>): {
+        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, contractInterfaces: Map<string, Interface>, options?: {
+        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;
+}