1. aepp-sdk 解决的是什么问题Python 开发者接 Aeternity 链时的工具链缺口1.1 为什么会在 Python 生态里遇到 aepp-sdk我最初接触 aepp-sdk 是因为一个内部数据工具的迁移需求。项目方给了我们一套跑在浏览器里的 JavaScript 示例要把它改成 Python 后台服务定时读取链上 AEX9 代币的持仓变动再把数据灌进内部数据库。JavaScript 示例在 Node 里跑得很顺畅但换到 Python 这边官方文档给的示例零散很多方法签名要靠翻源码才能看懂。所以这篇想把 aepp-sdk 在 Python 里的语法习惯、常用参数和几个能直接跑通的案例整理出来给后来的人省点排查时间。aepp-sdk 是 Aeternity 区块链的官方 Python SDK。它做的事情可以概括成三层第一层是底层 HTTP 调用把链上节点提供的 REST API 包装成了 Python 方法第二层是交易构造与签名负责把一笔操作转账、合约调用、代币转移编码成链上能识别的交易结构第三层是合约交互封装了 Sophia 合约的编译、部署、调用和事件解析。日常开发里我们用到最多的就是第二层和第三层。它用起来有点像 web3.py但细节上差别很大不能把既有经验直接搬过来。1.2 适合谁来用、解决哪些场景我觉得这个 SDK 最适合三类人。第一类是在做链上数据监控的需要定时拉取区块、交易、代币余额第二类是在做后台自动化工具的比如批量转账、代币归集、合约定时调用第三类是在做 DeFi 协议或钱包服务端需要构造交易并广播。如果你只是查一次余额用浏览器钱包就够了不必上 SDK但只要你开始写脚本、做调度任务、搞批量操作SDK 就是绕不开的底座。一个容易先入为主的误区是以为 aepp-sdk 只是个RPC 封装库调接口就行。实际用下来你会发现它把交易生命周期也管起来了——构造、签名、广播、等待上链。这带来的好处是你不需要自己拼 calldata 或者计算手续费坏处是你必须理解它的分层逻辑否则遇到参数不对时你根本不知道是哪一层出了问题。我后面会用一个合约调用案例把这条链路完整走一遍。2. 装环境这件事版本、依赖和最容易失误的地方2.1 正确的安装命令与版本选择aepp-sdk 的安装非常简单直接 pip 就能装pip install aepp-sdk但这里有一个非常关键的版本问题。SDK 目前主要维护两个大版本阶段早期版本是同步风格后面版本全面切到了 asyncio 异步风格。如果你在网上搜到老教程里面写的AENode、Chain这类类名在你新装的版本里可能已经被NodeClient替代了。我建议装完后先跑一段验证脚本确认当前装到的版本和 API 风格别急着照抄旧代码。pip show aepp-sdk看输出里的 Version 字段然后打开官方文档对应版本文档。我的经验是直接以当前 PyPI 最新版为准写新代码老项目如果锁定了旧版本就按老版本的 API 写不要混用。同步版和异步版混一起是非常常见的报错来源报错信息还不直观。2.2 编译器服务SDK 之外的隐藏依赖部署和调用 Sophia 合约时SDK 本身不负责把 Sophia 源码编成字节码它依赖一个独立的编译器 HTTP 服务。这也是新手最容易困惑的地方明明 SDK 装好了合约部署却一直报连接错误因为本机没起 compiler 服务。官方提供了编译器的 Docker 镜像docker run --rm -p 3080:3080 aeternity/aesophia_http如果你不想用 Docker也可以从源码构建但配置会多一些。开发环境建议直接用 Docker一条命令搞定。SDK 里的CompilerClient默认指向http://localhost:3080如果你的服务跑在别的端口或远程机器上需要在构造 client 时显式传入地址。提示aepp-sdk 连接链上节点和连接编译器是两个完全独立的网络地址。链上节点默认是主网https://mainnet.aeternity.io编译器默认是本地http://localhost:3080。很多人只配置了前者忘了后者导致合约操作三步卡在第一步。2.3 快速验证环境是否可用装完包之后我建议先写一个 20 行左右的脚本验证 SDK 能连通节点、能查到链上数据再往下做复杂功能。这个验证脚本也会帮你看清异步语法是否正确import asyncio from aeternity.node import NodeClient async def main(): client NodeClient(config{url: https://mainnet.aeternity.io}) height await client.get_height() print(current height:, height) await client.close() asyncio.run(main())如果你看到输出一个区块高度数字说明 SDK 安装、节点连接、异步调用这三级链路都没问题。注意两点一是get_height在旧版本里可能是同步方法没有await新版本则是异步二是 client 用完要关闭程序里长期挂着一个连接不释放跑大量任务时会有句柄泄漏的问题。这段脚本也是后面所有案例的基础结构。3. 核心语法与参数拆解看懂调用背后的编码逻辑3.1 最常用的顶层对象NodeClient 和 Accountaepp-sdk 里日常打交道最多的就是NodeClient和Account。NodeClient负责所有链上查询和交易广播。它通过一个config字典来接收参数最核心的是url也就是节点地址。还有network_id参数我在第 5 章会专门说它为什么容易出问题。它的方法命名比较直白get_height()查高度get_account(account_id)查账户post_transaction(tx)广播交易。Account则代表一个链上账户负责签名。构造方式有几种最常用的是从私钥恢复from aeternity.accounts import Account account Account.from_private_key_string(你的私钥十六进制字符串)这里的私钥格式要注意SDK 期望的是不带0x前缀的纯十六进制字符串。如果你拿到的私钥带0x最好先剥掉否则可能报长度校验错误。另一个常见操作是生成新账户from aeternity.accounts import Account account Account.generate() print(account.get_address()) print(account.get_private_key())get_address()返回的是以ak_开头的链上地址get_private_key()返回私钥十六进制字符串。生成后要立即备份千万别只存在临时变量里程序一退出就找不回来了。3.2 calldata 与各类型参数如何映射——得先懂一点编码规则但最关键的是直接传 Python 的dict作为 calldata不是的。SDK 需要的是 ABI 编码后的 calldata。所谓 ABI 编码就是把合约方法的函数名和参数列表编码成一串十六进制字节这样合约虚拟机才能识别它。实际代码里这个编码工作一般交给 SDK 的Contract对象或者编译器客户端来干。你如果手动拼 calldata大概率拼错。这里我先把类型对应关系放出来后面看代码会更容易Sophia 合约参数类型Python 类型说明intint普通整数但要注意范围链上合约一般是 256 位整数Python 的int没有范围限制超范围并不会提前报错要到上链后才会失败boolbool布尔值addressstr以ak_开头的地址字符串stringstr字符串list(...)list列表元素类型要匹配声明map(...)dict映射键值对类型要匹配声明option(...)None或对应类型可空类型Python 侧用None表示None用具体值表示Some(value)record(...)字典或对象记录类型SDK 里通常用字典表达这张表看着简单实际坑不少。最典型的是bool和int的区分Sophia 里bool和int编码差异很大你传True时 SDK 会做类型检查但有时你从 JSON 里解析出来的是1而不是True合约那边就会按整数解析行为完全对不上。所以我建议在调用合约前所有参数都先做好类型强转不要依赖 SDK 的隐式转换。3.3 Sophia 合约交互语法与 ABI 编码规则当我们说调用合约时实际要经历三个子步骤编译、部署、调用。在 aepp-sdk 里这三个步骤对应不同的调用方式。编译阶段你把 Sophia 源码交给编译器客户端from aeternity.compiler import CompilerClient async def compile_contract(): compiler CompilerClient(config{url: http://localhost:3080}) source_code open(counter.aes).read() bytecode await compiler.compile(source_code)编译出来的 bytecode 是部署好的交易要用的东西。部署阶段SDK 提供Contract对象from aeternity.contract import Contract contract await Contract.create( node_clientnode_client, accountaccount, sourcesource_code, bytecodebytecode, abisophia, compiler_urlhttp://localhost:3080, )部署成功之后contract对象上就有address属性了这是链上的合约地址。调用阶段用contract.call方法传方法名和参数result await contract.call( increment, args[], call_typecall, )这里call_type参数很重要它决定这是一次链上状态修改call还是一次只读查询static_call。如果方法会改状态比如计数器加一、转账用call如果只是查余额、查状态用static_call因为它不会消耗实际手续费。很多人在static_call上砸了真金白银就是因为少了这个区分。3.4 交易字段参数ttl、fee、nonce 的含义一次上链交易的核心字段只有几个但它们决定了交易是否有效、何时生效、费用多少。aepp-sdk 在构造交易时会自动填一部分但有几个参数需要你显式关心。nonce是账户的交易序号。链上为了防止重放攻击每个账户的交易必须按顺序递增。SDK 的Account通常会在广播前自动查询当前 nonce 再加一所以一般不用手动传。但如果你用的是多个进程并发给同一个账户签名就可能出现两个交易拿到同一个 nonce造成一个成功一个失败的情况。我在第 4 章的批量转账案例里会给出并发的处理方式。ttlTime To Live决定这笔交易在多长时间内有效。它本身是一个区块高度值意思是如果交易到 第 N ttl 高度的出块时间还没被打进区块这个交易就失效了。SDK 默认会给一个较大的值一般开发场景不用管。但如果你设置了较短的 ttl 来做定时交易就要注意节点打包延迟别设得太极限。fee则是交易手续费。Aeternity 的手续费是按交易类型和字节数计算的SDK 可以帮你自动估算但实际生产里我建议显式设置一个略高于最低值的 fee因为估算值有时在节点拥堵时不够用。注意这个 fee 的设置方法是transaction.fee value不同版本 API 不一致旧版本可能是tx.fee直接赋值新版本可能要求走 builder 参数写代码前先dir()看一下对象有哪些属性。4. 实际应用案例从查询余额到 AEX9 代币转账4.1 案例一账户余额与区块高度查询第一条代码是最经典的链上数据读取。我们来做一个能打印指定账户主网 AE 余额和当前区块高度的脚本import asyncio from aeternity.node import NodeClient async def main(): node_client NodeClient(config{url: https://mainnet.aeternity.io}) address ak_2rBdKpC9k2YVpE9n1nQmW2EKbLQxHvVZbbUAnE4iN8PaMQ5bFJ height await node_client.get_height() account_state await node_client.get_account(address) balance int(account_state[balance]) / 1e18 print(fheight: {height}) print(faddress: {address}) print(fbalance (AE): {balance:.6f}) await node_client.close() asyncio.run(main())这里有个隐藏细节get_account返回的balance单位是 aettos也就是链上的最小单位1 AE 10^18 aettos所以要除以 1e18 才是读者熟悉的 AE 数值。如果你忘掉这个换算读出来的数字会大得离谱。这个细节也适用于代币AEX9 代币的小数位数在代币合约里是单独定义的查询要用合约调用不能直接看账户余额体。另外get_account对不存在的地址会抛异常还是返回空结构实测下来它抛异常。所以如果要批量扫描大量地址最好对异常做捕获。我写这种脚本时会在外面包一层 try/except打印出出错的地址然后继续跑下一个而不是整个任务崩掉。4.2 案例二部署一个带状态的计数器合约接下来是完整的合约生命周期示例。先在本地建一个counter.aes文件内容是最简单的计数器合约contract Counter record state { count : int } entrypoint init() : state { count 0 } entrypoint increment() : unit put(state{ count state.count 1 }) entrypoint get_count() : int state.count这个合约做了三件事初始化时计数为 0调用increment时计数加 1调用get_count时返回当前计数。它足够简单但已经覆盖了状态读写、交易上链、只读查询三类核心操作。部署并调用的 Python 代码如下import asyncio from aeternity.node import NodeClient from aeternity.accounts import Account from aeternity.contract import Contract from aeternity.compiler import CompilerClient async def main(): node_client NodeClient(config{url: https://testnet.aeternity.io}) account Account.from_private_key_string(你的测试网私钥) compiler CompilerClient(config{url: http://localhost:3080}) source_code open(counter.aes).read() bytecode await compiler.compile(source_code) contract await Contract.create( node_clientnode_client, accountaccount, sourcesource_code, bytecodebytecode, abisophia, compiler_urlhttp://localhost:3080, ) print(deployed at:, contract.address) result await contract.call( increment, args[], call_typecall, ) print(increment tx hash:, result.hash) count await contract.call( get_count, args[], call_typestatic_call, ) print(count:, count.decode()) await node_client.close() await compiler.close() asyncio.run(main())这个例子值得注意的地方有三个。第一部署之前要先启动编译器服务否则compiler.compile会立刻抛连接错误。第二contract.call返回的是一个结果对象它有hash属性交易哈希和decode()方法把返回值解析成 Python 对象。第三测试网和主网的节点地址不一样私钥也不要混用。开发调试一律先走测试网既省钱又免得出安全事故。4.3 案例三AEX9 代币的余额查询和转账AEX9 是 Aeternity 链上的同质化代币标准类似以太坊的 ERC20。SDK 对它的封装很好不需要直接写合约调用用Token对象就能搞定。import asyncio from aeternity.node import NodeClient from aeternity.accounts import Account from aeternity.aex9 import TokenClient async def main(): node_client NodeClient(config{url: https://testnet.aeternity.io}) account Account.from_private_key_string(你的测试网私钥) token_address ct_1234567890abcdef # 代币合约地址 token await TokenClient.create( node_clientnode_client, accountaccount, contract_addresstoken_address, ) balance await token.balance_of(account.get_address()) print(balance:, balance) to_address ak_xxxxxx tx_hash await token.transfer(to_address, 100) print(transfer tx:, tx_hash) await node_client.close() asyncio.run(main())这段代码的两个关键参数是contract_address和转账数量。注意transfer的第二个参数是最小单位数量还是人类可读数量默认不是人类可读数量。它按代币合约定义的 decimals 来处理比如某个代币 decimals 6你要转 1 个完整代币就得传 1000000。写代码前先调用代币合约的decimals()方法确认或者直接查开发者文档。我见过不少人在这个小数位数上栽跟头转出去的数量比预期少了一万倍。还有一个容易踩的坑TokenClient.create内部其实是在做合约部署操作吗不是。它只是包装了一个已存在的合约地址不会帮你部署新代币。所以它并不需要 compiler 服务只要节点能访问到就行。4.4 案例四批量操作的并发控制做后台工具时最常遇到的问题是要给一长串地址批量转账代币。如果逐个await100 个地址串行执行每一笔都要等两个区块确认时间会拉得非常长。合理做法是用asyncio.gather做并发但这里有一个关键陷阱必须处理。Aeternity 的交易要求同一个账户的 nonce 必须连续。如果并发发 100 笔每个协程都去查同一个 nonce然后各自 1这 100 笔的 nonce 可能全部相同。链上只接受其中一笔其余全部失败。我的解决办法是外部管理 nonce先手动查一次最新 nonce然后每笔交易显式设置递增的 nonceimport asyncio from aeternity.node import NodeClient from aeternity.accounts import Account from aeternity.aex9 import TokenClient async def transfer_one(token, to_addr, amount, nonce): # 这里伪代码构建交易时显式把 nonce 传进去 ... async def main(): node_client NodeClient(config{url: https://testnet.aeternity.io}) account Account.from_private_key_string(你的私钥) token_address ct_xxxxx token await TokenClient.create(...) latest_height await node_client.get_height() account_state await node_client.get_account(account.get_address()) account_nonce account_state[nonce] addresses [ak_..., ak_..., ak_...] tasks [ transfer_one(token, addr, 10**6, account_nonce i 1) for i, addr in enumerate(addresses) ] await asyncio.gather(*tasks) asyncio.run(main())这里要注意两点第一查询 nonce 和实际签名广播之间有个时间差如果你的脚本同时跑在多个进程里光靠手动 nonce 也可能冲突想彻底避免就要引入分布式锁或数据库唯一约束第二并发量不是越大越好建议控制在 20 到 50 左右因为节点也会对同一 IP 的请求做限流量太大会收到 HTTP 429 错误。我一般会在代码里加一个asyncio.Semaphore(20)做并发闸门。5. 生产环境里的坑我踩过的和帮你提前避开的5.1 SDK 版本升级导致的 API 变化aepp-sdk 的版本演进不算快但破坏性变更不少。我踩过的最明显的一次是早期版本里Contract.call的返回值是一个TxResult直接用.decode()就能拿结果升级之后这个方法返回的对象上多了decoded属性老代码猛然就崩了。报错说AttributeError: TxResult object has no attribute decode。查这个问题花了我一个下午。后来我的对策是把所有 SDK 相关代码集中到一个chain_service.py模块里所有外界调用统一走这个模块SDK 升级时只改这个文件。这样即使 API 变了影响面也能控制。另外升级前一定先看CHANGELOG或者发行说明重点关注breaking changes段落。5.2 network_id 重放风险必须显式传参这是一个安全级别的问题。Aeternity 有主网和测试网两者共享同一套交易签名算法。如果你的代码把测试网签好的交易广播到主网理论上是有可能被接受的只要账户和交易结构合法。为了防止跨网络重放链上要求每笔交易绑定一个network_id字符串主网是ae_mainnet测试网是ae_uat。SDK 在构造交易时network_id是从NodeClient的配置里读取的。如果你在测试网环境切换主网时只改了节点 URL忘了改network_id签出来的交易在主网会被拒绝。反过来也一样。这个参数平时安静地藏在配置里不出声等出了事才让人想起来。我现在的习惯是在配置里把它写成常量并在构造 client 时显式检查node_config { url: https://mainnet.aeternity.io, network_id: ae_mainnet, } node_client NodeClient(confignode_config)如果你负责的项目同时连接主网和测试网建议把两个node_config分别建好用环境变量切分不要在一个进程里改来改去。5.3 fee 估算与实际广播失败的排查我在测试环境跑转账脚本时有一段时间总是偶发广播失败错误信息是Transaction has been declined或者Invalid fee。一开始我以为是手续费算错了后来打印出实际广播的交易体才发现fee字段的值接近 0。原因说出来有点好笑我在构造交易之后给交易对象重新赋值了fee字段但那个字段名在新版本里变成了fee而老代码里用的是gas_price之类的旧字段名赋值后没有生效。这类问题给我的教训是fee最好让 SDK 自动算不要手动覆盖除非你清楚每个版本里fee对应的确切属性路径。如果一定要手动设必须把最终交易体打印出来用节点接口做一个dry-run验证。Aeternity 节点提供了POST /v3/dry-run接口SDK 里集成了相应方法广播前先跑一遍 dry-run能拦截大部分无效交易。5.4 日志和调试把底层请求打出来的方法遇到玄学问题我第一个动作不是读文档而是打开 SDK 的底层日志。aepp-sdk 是基于requests和aiohttp做的所以你可以用标准库的日志模块把 HTTP 请求和响应打出来import logging logging.basicConfig(levellogging.DEBUG)这样运行你的脚本时SDK 发出去的每个 HTTP 请求、收到的每个响应都会显示在终端里。你会看到它到底请求了哪个 URL传了什么参数节点返回什么错误。很多为什么合约调用失败的问题答案就在这个日志里要么是 compiler 服务没启动要么是参数类型不对要么是地址前缀错误。比直接看日志更快的一个小技巧是在调contract.call之前先调用contract.get_contract_methods()看一下这个合约暴露的方法列表和方法签名。这个方法会从合约源码或已部署的 ABI 里解析出所有可调用方法能帮你确认方法名拼写和参数个数是否一致。合约方法名拼错了SDK 的报错往往很晚才出现等到广播上链阶段才暴露费时费力。从实际项目的角度说aepp-sdk 并不完美文档零散、版本变化多、跟以太坊系列工具链的体验差距不小。但只要你理清了三层结构——节点连接、交易构造、合约交互——后面的大部分问题都是细节排查。我在第 4 章给的四个案例就是最常见的使用模式了把它们跑通你基本就具备了用 Python 跟 Aeternity 链进行自动化交互的能力。如果后续再遇到具体问题优先看 SDK 源码和编译器的接口文档比搜二手经验靠谱得多。