在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位整数）无法直接存储整个字符串，因此需要将字符串拆解并编码。最常见的策略是：
立即学习“Python免费学习笔记（深入）”；
- 字符拆解： 将字符串拆解为单个字符。
- ASCII/UTF-8编码： 将每个字符转换为其对应的整数值。对于英文字符，通常是其ASCII值。如果涉及多字节字符（如中文），则需要考虑UTF-8编码，并将每个字节视为一个独立的u64元素，或者根据合约的设计将多字节字符编码为单个felt。
- 数组构造： 将这些整数值构成一个数组，并按照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())注意事项
-
字符编码： 上述 string_to_calldata_array 函数默认将每个字符转换为其ASCII值。如果您的字符串包含非ASCII字符（如中文、表情符号等），并且Starknet合约期望处理这些字符，您需要：
- 将Python字符串先编码为字节串（例如 long_string.encode('utf-8')）。
- 然后将字节串中的每个字节转换为一个整数，作为calldata的元素。
- 确保Starknet合约端有相应的逻辑来解码这些字节，并将其重构成原始字符串。
- Gas费用： 传递长字符串会显著增加交易的calldata大小，进而导致更高的Gas费用。在设计应用时，应充分评估传递数据的长度对交易成本的影响。对于非常大的数据，可能需要考虑链下存储和链上哈希验证的方案。
-
合约逻辑匹配： 确保Starknet合约中接收字符串的函数参数类型与calldata的编码格式完全匹配。通常，合约函数会期望一个 Array
或 felt* 类型的参数，并在合约内部通过索引和长度来访问和解释这些 felt 值。 - 最大长度限制： 尽管理论上u64数组可以很长，但实际操作中仍会受限于Starknet网络对交易最大calldata大小和Gas消耗的限制。
总结
在Starknet中与合约进行交互时，正确理解和构造calldata，尤其是对于数组和字符串这类复杂数据类型，是至关重要的。通过将长字符串拆解为字符（或字节）数组，并遵循Starknet calldata 的长度前缀约定，可以有效地避免“输入过长”的错误。开发者应始终关注数据编码细节、Gas成本以及合约端的数据解析逻辑，以确保链上交互的顺畅和高效。
