跳到主要内容

Get 方法

备注

在继续之前，建议读者对FunC编程语言和TON区块链上的智能合约开发有基本的了解。这将有助于您更有效地理解这里提供的信息。

介绍​

Get方法是智能合约中用于查询特定数据的特殊函数。它们的执行不需要任何费用，并且在区块链之外进行。

这些函数对于大多数智能合约来说都非常常见。例如，默认的钱包合约有几个get方法，如seqno()、get_subwallet_id()和get_public_key()。它们被钱包、SDK和API用来获取有关钱包的数据。

Get 方法的设计模式​

基本 get 方法设计模式​

  1. 单一数据点检索：一种基本设计模式是创建返回合约状态中单个数据点的方法。这些方法没有参数，并返回单个值。

    示例：

    int get_balance() method_id {
        return get_data().begin_parse().preload_uint(64);
    }

  2. 聚合数据检索：另一种常见的模式是创建一次返回合约状态中多个数据点的方法。这通常在某些数据点一起使用时采用。这些在Jetton和NFT合约中非常常见。

    示例：

    (int, slice, slice, cell) get_wallet_data() method_id {
        return load_data();
    }

高级 get 方法设计模式​

  1. 计算数据检索：在某些情况下，需要检索的数据并不直接存储在合约的状态中，而是根据状态和输入参数计算得出的。

    示例：

    slice get_wallet_address(slice owner_address) method_id {
        (int total_supply, slice admin_address, cell content, cell jetton_wallet_code) = load_data();
        return calculate_user_jetton_wallet_address(owner_address, my_address(), jetton_wallet_code);
    }

  2. 条件数据检索：有时需要检索的数据取决于某些条件，如当前时间。

    示例：

    (int) get_ready_to_be_used() method_id {
        int ready? = now() >= 1686459600;
        return ready?;
    }

最常见的 get 方法​

标准钱包​

seqno()​

int seqno() method_id {
    return get_data().begin_parse().preload_uint(32);
}

返回特定钱包中交易的序列号。这个方法主要用于重放保护。

get_subwallet_id()​

int get_subwallet_id() method_id {
    return get_data().begin_parse().skip_bits(32).preload_uint(32);
}

get_public_key()​

int get_public_key() method_id {
    var cs = get_data().begin_parse().skip_bits(64);
    return cs.preload_uint(256);
}

检索与钱包关联的公钥。

Jettons​

get_wallet_data()​

(int, slice, slice, cell) get_wallet_data() method_id {
    return load_data();
}

这个方法返回与Jetton钱包相关的完整数据集：

  • (int) 余额
  • (slice) 持有者地址
  • (slice) Jetton主合约地址
  • (cell) Jetton钱包代码

get_jetton_data()​

(int, int, slice, cell, cell) get_jetton_data() method_id {
    (int total_supply, slice admin_address, cell content, cell jetton_wallet_code) = load_data();
    return (total_supply, -1, admin_address, content, jetton_wallet_code);
}

返回Jetton主合约的数据，包括其总供应量、管理员地址、Jetton内容和钱包代码。

get_wallet_address(slice owner_address)​

slice get_wallet_address(slice owner_address) method_id {
    (int total_supply, slice admin_address, cell content, cell jetton_wallet_code) = load_data();
    return calculate_user_jetton_wallet_address(owner_address, my_address(), jetton_wallet_code);
}

根据所有者的地址，此方法计算并返回所有者的Jetton钱包合约地址。

NFTs​

get_nft_data()​

(int, int, slice, slice, cell) get_nft_data() method_id {
    (int init?, int index, slice collection_address, slice owner_address, cell content) = load_data();
    return (init?, index, collection_address, owner_address, content);
}

返回与非同质化代币相关的数据，包括是否已初始化、在集合中的索引、集合地址、所有者地址和个体内容。

get_collection_data()​

(int, cell, slice) get_collection_data() method_id {
    var (owner_address, next_item_index, content, _, _) = load_data();
    slice cs = content.begin_parse();
    return (next_item_index, cs~load_ref(), owner_address);
}

返回NFT集合的数据，包括下一个要铸造的项目索引、集合内容和所有者地址。

get_nft_address_by_index(int index)​

slice get_nft_address_by_index(int index) method_id {
    var (_, _, _, nft_item_code, _) = load_data();
    cell state_init = calculate_nft_item_state_init(index, nft_item_code);
    return calculate_nft_item_address(workchain(), state_init);
}

给定索引，此方法计算并返回该集合的相应NFT项目合约地址。

royalty_params()​

(int, int, slice) royalty_params() method_id {
    var (_, _, _, _, royalty) = load_data();
    slice rs = royalty.begin_parse();
    return (rs~load_uint(16), rs~load_uint(16), rs~load_msg_addr());
}

获取NFT的版税参数。这些参数包括原始创作者在NFT被出售时应支付的版税百分比。

get_nft_content(int index, cell individual_nft_content)​

cell get_nft_content(int index, cell individual_nft_content) method_id {
    var (_, _, content, _, _) = load_data();
    slice cs = content.begin_parse();
    cs~load_ref();
    slice common_content = cs~load_ref().begin_parse();
    return (begin_cell()
            .store_uint(1, 8) ;; offchain tag
            .store_slice(common_content)
            .store_ref(individual_nft_content)
            .end_cell());
}

给定索引和个体NFT内容，此方法获取并返回NFT的常见内容和个体内容。

如何使用 get 方法​

在流行的浏览器上调用 get 方法​

Tonviewer​

您可以在页面底部的"Methods"标签中调用get方法。

您可以在"Get methods"标签中调用get方法。

从代码中调用 get 方法​

我们将使用以下Javascript库和工具来提供以下示例：

假设有一个合约，其中有以下get方法：

(int) get_total() method_id {
    return get_data().begin_parse().preload_uint(32); ;; load and return the 32-bit number from the data
}

这个方法从合约数据中返回一个单一的数字。

下面的代码片段可以用来在已知地址的某个合约上调用这个get方法：

import { Address, TonClient } from 'ton';

async function main() {
    // Create Client
    const client = new TonClient({
        endpoint: 'https://toncenter.com/api/v2/jsonRPC',
    });

    // Call get method
    const result = await client.runMethod(
        Address.parse('EQD4eA1SdQOivBbTczzElFmfiKu4SXNL4S29TReQwzzr_70k'),
        'get_total'
    );
    const total = result.stack.readNumber();
    console.log('Total:', total);
}

main();

这段代码将输出Total: 123。数字可能会有所不同，这只是一个例子。

测试 get 方法​

对于我们创建的智能合约的测试，我们可以使用沙盒，它默认安装在新的Blueprint项目中。

首先，您需要在合约包装器中添加一个特殊方法，以执行get方法并返回类型化的结果。假设您的合约叫做Counter，您已经实现了更新存储数字的方法。那打开wrappers/Counter.ts并添加以下方法：

async getTotal(provider: ContractProvider) {
    const result = (await provider.get('get_total', [])).stack;
    return result.readNumber();
}

它执行get方法并获取结果堆栈。堆栈在get方法的情况下基本上就是它所返回的东西。在这个片段中，我们从中读取一个单一的数字。在更复杂的情况下，一次返回多个值时，您可以多次调用readSomething类型的方法来从堆栈中解析整个执行结果。

最后，我们可以在测试中使用这个方法。导航到tests/Counter.spec.ts并添加一个新的测试：

it('should return correct number from get method', async () => {
    const caller = await blockchain.treasury('caller');
    await counter.sendNumber(caller.getSender(), toNano('0.01'), 123);
    expect(await counter.getTotal()).toEqual(123);
});

通过在终端运行npx blueprint test来检查，如果您做得正确，这个测试应该被标记为通过！

从其他合约调用 get 方法​

与直觉相反，从其他合约调用get方法在链上是不可能的，主要是由于区块链技术的性质和需要达成共识。

首先，从另一个分片链获取数据可能需要时间。这种延迟可能很容易中断合约执行流程，因为区块链操作需要以确定和及时的方式执行。

其次，达成验证者之间的共识将是有问题的。为了验证交易的正确性，验证者也需要调用相同的get方法。然而，如果目标合约的状态在这些多次调用之间发生变化，验证者可能会得到不同的交易结果版本。

最后，TON中的智能合约被设计为纯函数：对于相同的输入，它们总是产生相同的输出。这一原则使得消息处理过程中的共识变得简单直接。引入运行时获取任意动态变化数据的能力将打破这种确定性属性。

对开发者的影响​

这些限制意味着一个合约不能通过其get方法直接访问另一个合约的状态。无法在确定性的合约流程中纳入实时外部数据可能看起来有限制。然而，正是这些约束确保了区块链技术的完整性和可靠性。

解决方案和变通方法​

在TON区块链中，智能合约通过消息进行通信，而不是直接从另一个合约调用方法。向目标合约发送请求执行特定方法的消息。这些请求通常以特殊的操作码开头。

被设计为接受这些请求的合约将执行所需的方法，并在单独的消息中发送结果。虽然这可能看起来很复杂，但它实际上简化了合约之间的通信，并提高了区块链网络的可扩展性和性能。

这种消息传递机制是TON区块链运作的一个整体部分，为可扩展网络增长铺平了道路，而无需在分片之间进行广泛的同步。

为了有效的合约间通信，至关重要的是您的合约被设计为正确接受和响应请求。这包括指定可以在链上调用以返回响应的方法。

让我们考虑一个简单的例子：

#include "imports/stdlib.fc";

int get_total() method_id {
    return get_data().begin_parse().preload_uint(32);
}

() recv_internal(int my_balance, int msg_value, cell in_msg_full, slice in_msg_body) impure {
    if (in_msg_body.slice_bits() < 32) {
        return ();
    }

    slice cs = in_msg_full.begin_parse();
    cs~skip_bits(4);
    slice sender = cs~load_msg_addr();

    int op = in_msg_body~load_uint(32); ;; load the operation code

    if (op == 1) { ;; increase and update the number
        int number = in_msg_body~load_uint(32);
        int total = get_total();
        total += number;
        set_data(begin_cell().store_uint(total, 32).end_cell());
    }
    elseif (op == 2) { ;; query the number
        int total = get_total();
        send_raw_message(begin_cell()
            .store_uint(0x18, 6)
            .store_slice(sender)
            .store_coins(0)
            .store_uint(0, 107) ;; default message headers (see sending messages page)
            .store_uint(3, 32) ;; response operation code
            .store_uint(total, 32) ;; the requested number
        .end_cell(), 64);
    }
}

在这个示例中，合约接收并处理内部消息，通过解读操作码、执行特定方法和适当地返回响应：

  • 操作码1表示更新合约数据中的数字的请求。
  • 操作码2表示从合约数据中查询数字的请求。
  • 操作码3用于响应消息，发起调用的智能合约必须处理以接收结果。

为了简单起见，我们只是使用了简单的小数字1、2和3作为操作码。但对于真实项目，请根据标准设置它们：

常见陷阱及如何避免​

  1. 误用 get 方法：如前所述，get方法被设计用于从合约的状态返回数据，不是用来更改合约的状态。尝试在get方法中更改合约的状态实际上不会这样做。

  2. 忽略返回类型：每个get方法都应该有一个明确定义的返回类型，与检索的数据相匹配。如果一个方法预期返回特定类型的数据，请确保该方法的所有路径都返回此类型。避免使用不一致的返回类型，因为这可能导致与合约交互时出现错误和困难。

  3. 假设跨合约调用：一个常见的误解是可以从链上的其他合约调用get方法。然而，如我们所讨论的，这是不可能的，因为区块链技术的性质和需要达成共识的需求。始终记住，get方法旨在链下使用，合约间的链上交互是通过内部消息完成的。

结论​

Get方法是TON区块链中查询智能合约数据的重要工具。尽管它们有其局限性，但了解这些限制并知道如何克服它们是有效使用智能合约中的get方法的关键。