Starknet合约传递长字符串Python教程

在Starknet中向合约传递长字符串时，直接作为单个参数会导致“输入过长”错误。正确的做法是，将字符串的每个字符编码为独立的`u64`值，并以数组形式传递。`calldata`的约定要求数组的长度必须作为第一个参数提供，随后才是实际的字符元素。本文将详细阐述这一编码策略及其Python实现。

理解Starknet Calldata的数组约定

Starknet的合约在接收数组类型参数时，其calldata的编码方式与传统编程语言有所不同。为了明确数组的边界和内容，Starknet要求在传递数组元素之前，首先提供数组的长度。其通用格式如下：

[数组长度, 元素1, 元素2, ..., 元素N]

例如，如果一个合约函数期望接收一个整数数组 [8, 13, 21, 34]，那么在构造 calldata 时，需要将其编码为 [4, 8, 13, 21, 34]。这里的 4 表示数组中包含四个元素，紧随其后的是这四个实际的元素值。

长字符串的编码策略

当我们需要向Starknet合约传递一个长字符串时，由于Starknet的felt类型（通常是252位整数）无法直接存储整个字符串，因此需要将字符串拆解并编码。最常见的策略是：

1. 字符拆解： 将字符串拆解为单个字符。
2. ASCII/UTF-8编码： 将每个字符转换为其对应的整数值。对于英文字符，通常是其ASCII值。如果涉及多字节字符（如中文），则需要考虑UTF-8编码，并将每个字节视为一个独立的u64元素，或者根据合约的设计将多字节字符编码为单个felt。
3. 数组构造： 将这些整数值构成一个数组，并按照Starknet的数组约定，在数组前添加其长度。

例如，字符串 "abc" 将被编码为：

• 字符 'a' 对应 ASCII 值 97
• 字符 'b' 对应 ASCII 值 98
• 字符 'c' 对应 ASCII 值 99 最终的 calldata 序列将是 [3, 97, 98, 99]。

Python实现

以下是如何在Python中实现这一编码策略，并将其集成到Starknet交易发送流程中的示例代码：

import aiohttp
from starknet_py.net.full_node_client import FullNodeClient
from starknet_py.net.account.account import Account
from starknet_py.net.models import StarknetChainId
from starknet_py.net.signer.models import KeyPair
from starknet_py.net.client_models import Call
from starknet_py.hash.selector import get_selector_from_name

# 假设这些变量已根据您的实际环境进行定义
NODE_URL = "YOUR_NODE_URL" # 例如 "https://alpha-mainnet.starknet.io/rpc/v0.4"
ACCOUNT_ADDRESS = 0x123... # 您的账户地址
PRIVATE_KEY = 0xabc... # 您的私钥

def string_to_calldata_array(long_string: str) -> list[int]:
    """
    将长字符串转换为Starknet calldata所需的u64数组格式。
    每个字符转换为其ASCII值，并以数组长度作为前缀。
    """
    # 将字符串中的每个字符转换为其ASCII值
    # 注意：这里假设合约期望的是ASCII编码。对于非ASCII字符，
    # 您可能需要将字符串先编码为字节串（如.encode('utf-8')），
    # 然后将每个字节转换为整数。
    char_values = [ord(char) for char in long_string]

    # Starknet calldata约定：[长度, 元素1, 元素2, ...]
    return [len(char_values)] + char_values

async def invoke_contract_with_long_string():
    """
    演示如何向Starknet合约传递一个长字符串。
    """
    async with aiohttp.TCPConnector(ssl=False) as tcpconnector:
        async with aiohttp.ClientSession(connector=tcpconnector, trust_env=True) as session:
            full_node_client = FullNodeClient(node_url=NODE_URL, session=session)
            account = Account(
                client=full_node_client,
                address=ACCOUNT_ADDRESS,
                key_pair=KeyPair.from_private_key(key=PRIVATE_KEY),
                chain=StarknetChainId.MAINNET,
            )

            # 待传递的长字符串数据
            long_data_string = "data:,{\"p\":\"stark-20\",\"op\":\"mint\",\"tick\":\"STRK\",\"amt\":\"1000\"}"

            # 将长字符串转换为Starknet calldata所需的格式
            calldata_for_string = string_to_calldata_array(long_data_string)

            # 目标合约地址和函数选择器
            target_contract_address = 0x07341189e3c96f636a4192cfba8c18deeee33a19c5d0425a26cf96ea42388c4e
            selector_name = "inscribe"

            call = Call(
                to_addr=target_contract_address,
                selector=get_selector_from_name(selector_name),
                calldata=calldata_for_string # 使用正确编码后的calldata
            )

            calls = [call]

            # 签署交易（初始max_fee可设为0，之后进行估算）
            tx = await account.sign_invoke_transaction(
                calls=calls, max_fee=0
            )

            # 估算交易费用
            estimated_fee = await account.client.estimate_fee(tx=tx)
            print(f"估算费用: {estimated_fee.overall_fee} wei")

            # 实际发送交易前，通常需要用估算出的费用更新交易并重新签名
            # tx.max_fee = estimated_fee.overall_fee
            # invoke_response = await account.client.send_transaction(tx)
            # print(f"交易哈希: {invoke_response.transaction_hash}")

# 在实际运行中，您需要取消以下行的注释
# import asyncio
# asyncio.run(invoke_contract_with_long_string())

注意事项

1. 字符编码： 上述 string_to_calldata_array 函数默认将每个字符转换为其ASCII值。如果您的字符串包含非ASCII字符（如中文、表情符号等），并且Starknet合约期望处理这些字符，您需要：
   • 将Python字符串先编码为字节串（例如 long_string.encode('utf-8')）。
   • 然后将字节串中的每个字节转换为一个整数，作为calldata的元素。
   • 确保Starknet合约端有相应的逻辑来解码这些字节，并将其重构成原始字符串。
2. Gas费用： 传递长字符串会显著增加交易的calldata大小，进而导致更高的Gas费用。在设计应用时，应充分评估传递数据的长度对交易成本的影响。对于非常大的数据，可能需要考虑链下存储和链上哈希验证的方案。
3. 合约逻辑匹配： 确保Starknet合约中接收字符串的函数参数类型与calldata的编码格式完全匹配。通常，合约函数会期望一个 Array 或 felt* 类型的参数，并在合约内部通过索引和长度来访问和解释这些 felt 值。
4. 最大长度限制： 尽管理论上u64数组可以很长，但实际操作中仍会受限于Starknet网络对交易最大calldata大小和Gas消耗的限制。

总结

在Starknet中与合约进行交互时，正确理解和构造calldata，尤其是对于数组和字符串这类复杂数据类型，是至关重要的。通过将长字符串拆解为字符（或字节）数组，并遵循Starknet calldata 的长度前缀约定，可以有效地避免“输入过长”的错误。开发者应始终关注数据编码细节、Gas成本以及合约端的数据解析逻辑，以确保链上交互的顺畅和高效。