GenLayer CLI 实战指南：部署、交互与调试智能合约的全命令手册

genlayer命令行工具是 GenLayer 智能合约（Intelligent Contract）开发全流程的核心入口，负责合约部署、链上交互、交易检查与网络配置，可无缝对接本地 GenLayer Studio、studio.genlayer.com 托管服务以及 Testnet Bradbury 测试网。读完本文，你将掌握从安装、网络切换、账户管理、资金充值、合约部署与读写调用，到利用receipt排查交易执行结果、发起appeal申诉的完整实战能力，并理解生命周期状态与执行成败之间的关键区别——这是避免把合约错误误判为基础设施故障的最重要一环。

在互联网法院（Internet Court）的六层技术栈中，GenLayer 位于第 6 层"验证与争议解决"（详见 README.md 中的分层表），本仓库的vendored/genlayer/目录下随附了 write-contract、direct-tests、integration-tests、genvm-lint 等配套技能，与本文的 CLI 使用构成完整的开发闭环。

安装

GenLayer CLI 通过 npm 全局安装：

npm install -g genlayer

安装完成后即可在任何目录下直接调用genlayer子命令。该技能在 Agent 环境中被声明为可使用 Bash 与 Read 工具（见 vendored/genlayer/genlayer-cli/agents/openai.yaml），即所有操作均通过命令行完成，返回结果以文本形式读取分析。

网络配置

CLI 内置了多个 GenLayer 网络，通过genlayer network系列命令切换：

genlayer network set # 交互式选择器 genlayer network set testnet-bradbury # 直接指定 genlayer network info # 显示当前网络配置 genlayer network list # 列出全部网络

内置网络清单：localnet（本地 Studio）、studionet（托管 Studio，即 studio.genlayer.com）、testnet-asimov、testnet-bradbury（测试网）。

StudioNet 无 Gas 特性

studionet是免 Gas 网络——无需任何代币即可部署合约和发起交互，账户余额为 0 GEN 是预期且正常的状态，不会阻止任何操作。这意味着在托管 Studio 上做冒烟测试或原型验证时，可以完全跳过资金充值环节。

速率限制与队列上限

studionet按 IP 限流：60 req/min、1000 req/hr、10000 req/day。这些限制不是永久封禁——触发后只是在本窗口（分钟/小时/天）周期内拒绝后续请求，窗口重置后自动恢复。两个典型错误码需要区分：

实战建议：批量脚本必须做节流（throttle），每笔提交之间等待交易收据返回，不要并行连发。大批量压力测试优先使用localnet。此限流策略在 integration-tests 的 Common Issues 中也有印证——重度测试套件应切到 localnet（GLSim 或本地 Studio），并对.transact()调用做节奏控制。

为什么优先用 network set 而非 --rpc

内置网络永远使用genlayer network set，不要用--rpc参数。--rpc会绕过链配置——包括共识合约 ABI、isStudio标志等——从而导致交易轮询失败。只有当目标网络不在内置列表中（自定义/私有网络）时才使用--rpc。

账户管理

genlayer account # 显示当前活动账户（地址、余额、网络） genlayer account list # 列出所有账户 genlayer account create --name dev1 # 创建新账户 genlayer account use dev1 # 切换活动账户 genlayer account unlock # 将密钥缓存到操作系统钥匙串（之后无需输密码） genlayer account lock # 从钥匙串移除 # 从私钥或 keystore 导入 genlayer account import --name imported --private-key 0x... genlayer account import --name imported --keystore ./keystore.json # 发送代币 genlayer account send 0x123...abc 10gen

金额格式支持三种写法："10gen"、"0.5gen"或裸 wei 数值"1000000000000000000"（即 1 GEN 的 10^18 单位）。这一 atto 量级约定与 write-contract 中的存储规范一致——跨链互操作与资金相关的链上金额一律使用u256+ atto 刻度（value × 10^18），是区块链行业的标准做法。

非交互式用法（CI/CD、容器、Agent）

account create、account import、account send支持--password <password>参数跳过交互提示：

genlayer account create --name dev1 --password "mypassword" genlayer account import --name imported --private-key 0x... --password "mypassword"

account unlock依赖操作系统钥匙串（macOS Keychain、GNOME Keyring 等），在无头容器（headless container）中会直接失败。当账户处于锁定状态时，所有需要签名的命令（deploy、write、appeal、account send）都会提示输入 keystore 密码。要自动化这些操作，可以通过 stdin 管道喂入密码：

echo "mypassword" | genlayer deploy --contract contracts/my_contract.py --args "arg1"

资金充值

新账户默认余额为 0 GEN，是否需要充值取决于目标网络：

• StudioNet 免 Gas——0 GEN 余额即可部署和交互，属于预期正常状态，完全跳过充值步骤。
• 测试网（Bradbury、Asimov）——部署或写入前必须先充值。

测试网充值流程（官方 Testnet Faucet，即 testnet-faucet.genlayer.foundation）：

1. 获取地址：运行genlayer account，复制address字段；
2. 在浏览器中打开 Faucet 页面，粘贴地址并领取 100 GEN（每 24 小时一次）；
3. 验证：再次运行genlayer account，确认余额已更新。

注意：Faucet 使用 Cloudflare Turnstile 人机验证，无法从 CLI 自动化——必须由用户手动在浏览器中领取。该 Faucet 同时适用于 Testnet Bradbury 和 Testnet Asimov。

合约部署

# 部署指定合约 genlayer deploy --contract contracts/my_contract.py genlayer deploy --contract contracts/my_contract.py --args "arg1" 42 # 运行 deploy/ 目录下的全部部署脚本 genlayer deploy

不带参数时，genlayer deploy会依次执行deploy/文件夹中的全部部署脚本，适合一次性初始化多合约环境。部署前务必先通过genvm-lint check校验合约（详见下文"与周边工具协同"）。

合约交互

Read（只读，不产生交易）

genlayer call <address> <method> genlayer call 0x123...abc get_data --args "key1"

Write（发送交易，改变状态）

genlayer write <address> <method> genlayer write 0x123...abc set_data --args "hello"

检查合约

genlayer schema <address> # 方法签名与类型（ABI） genlayer code <address> # 合约源码

schema用于确认方法是否存在、参数类型是否正确；code用于核对链上部署代码与本地代码是否一致——这两条命令在下面的调试工作流中是排查问题的标准步骤。

交易调试：receipt 命令

genlayer receipt是最常用的调试命令——查看一笔交易内部到底发生了什么：

# 获取完整回执（默认等待 FINALIZED 状态） genlayer receipt <txHash> # 只看执行产生的 stdout 或 stderr genlayer receipt <txHash> --stdout genlayer receipt <txHash> --stderr # 等待某个生命周期状态 genlayer receipt <txHash> --status PENDING genlayer receipt <txHash> --status ACCEPTED genlayer receipt <txHash> --status FINALIZED # 自定义重试行为 genlayer receipt <txHash> --retries 50 --interval 3000

--retries控制轮询次数，--interval为每次轮询间隔（毫秒），适合慢网络或高负载场景下延长等待窗口。

交易生命周期

生命周期状态依次为：SUBMITTED->PENDING->ACCEPTED->FINALIZED。

关键认知：生命周期状态 ≠ 执行成功

ACCEPTED和FINALIZED只代表网络接受/终态化了这笔交易的"结果"，并不代表合约代码执行成功。这是最容易踩坑、也最值得记住的一条：

• 如果合约执行失败，交易依然可能走到ACCEPTED乃至FINALIZED，但状态变更不会被应用；
• 对于部署交易，执行失败意味着没有创建任何合约——此时genlayer code、genlayer schema、eth_getCode或gen_getContractSchema查不到合约是完全预期的，不要误判为基础设施故障。

同一结论在 integration-tests 中被反复强调：写方法返回的交易回执必须先断言tx_execution_succeeded(receipt)，再读取状态或检查 schema/code，否则"缺少合约"会被错误归因于 RPC、索引器或状态读取问题。

调试决策表

拿到一笔交易后，按以下对照判断：

申诉一笔交易

genlayer appeal <txHash>

appeal用于挑战一笔交易的结果，触发验证者重新评估（re-run consensus）。这与智能合约层的共识机制呼应——write-contract 指出，当验证者无法就 leader 输出达成一致时，交易会被驳回并要求重试/轮换，appeal是用户侧显式发起这一流程的命令入口。

本地 Studio 管理

genlayer init # 初始化环境 genlayer init --numValidators 10 --headless # 自定义：10 个验证者、无头模式 genlayer up # 启动 Studio genlayer up --reset-db # 全新启动（重置数据库） genlayer stop # 停止所有服务

--numValidators控制本地验证者数量（影响共识验证的并行度），--headless适合无图形界面的 CI/容器环境，--reset-db用于彻底清理历史状态、获得干净链。

本地验证者管理

genlayer localnet validators get # 列出全部 genlayer localnet validators count # 计数 genlayer localnet validators create --stake 50 # 新增一个（质押 50） genlayer localnet validators create-random --count 3 # 批量新增 3 个 genlayer localnet validators update 0x... --model gpt-4 # 更换模型 genlayer localnet validators delete --address 0x... # 删除

本地验证者可配置使用的模型（如--model gpt-4），用于模拟不同验证者执行非确定性任务时的判断行为。

标准调试工作流

当一笔交易失败或产生意外结果时，按此顺序排查：

1. 拿回执：genlayer receipt <txHash> --stdout --stderr——先看执行阶段的实际输出；
2. 检查执行结果：生命周期状态不能单独作为依据，ACCEPTED/FINALIZED可能包含执行错误；
3. 检查合约 schema：genlayer schema <address>——确认方法存在、参数正确；
4. 读取合约源码：genlayer code <address>——核对链上代码与本地代码一致；
5. 尝试只读调用：genlayer call <address> <view_method>——检查当前链上状态；
6. 必要时申诉：genlayer appeal <txHash>——触发共识重跑。

这套流程的关键在于"先验证执行结果，再归因基础设施"，与上述 receipt 决策表配合，能快速把合约错误与网络问题区分开。

项目脚手架

genlayer new myproject # 从模板创建项目 genlayer new myproject --path ./projects/

genlayer new从官方模板生成项目骨架，--path指定生成位置。脚手架项目自带contracts/、deploy/等目录约定，与genlayer deploy的默认扫描路径（deploy/文件夹）以及 genvm-lint 中提到的requirements.txt（内含genvm-linter）衔接。

配置管理

genlayer config get # 显示全部配置 genlayer config get network # 查看指定键 genlayer config set network=testnet-bradbury genlayer config reset network # 恢复默认值

配置以键值对形式持久化，network键即当前网络选择；config reset network可随时回到出厂默认网络。

与周边工具协同：完整的合约开发生命周期

genlayer-cli只是 GenLayer 开发工具链的一环，本仓库vendored/genlayer/下的其他四个技能与它配合构成标准工作流：

1. 编写（write-contract）：每个合约首行必须固定 runner 版本哈希（如# { "Depends": "py-genlayer:1jb45aa8ynh2a9c9xn3b7qqh8sm5q93hwfp7jqmwsfhh8jpz09h6" }），所有 GenLayer 网络都会拒绝test、latest及未固定版本的 runner 别名；
2. 静态检查（genvm-lint）：部署前运行genvm-lint check contracts/my_contract.py，一次完成 AST 安全 lint 与 SDK 语义 validate，同时可用genvm-lint schema预取 ABI；
3. 直接模式测试（direct-tests）：pytest tests/direct/ -v，毫秒级内存测试，不启动服务器，覆盖业务逻辑、校验、状态流转，但不执行验证者逻辑；
4. 集成测试（integration-tests）：gltest tests/integration/ -v -s --network studionet，跑真实共识（leader + validators），验证等价性原则与真实 Web/LLM 调用；
5. 部署与运维（本文）：genlayer network set切换网络 →genlayer account管理账户 →genlayer deploy部署 →genlayer receipt检查回执 →genlayer appeal申诉。

其中直接模式与集成模式的取舍可参照 integration-tests 的对比表：直接模式约 30ms、仅 leader 单方执行、可 mock Web/LLM；集成模式秒级到分钟级、完整共识、真实外部调用，是部署前的最终验证环节。当收到-32429/-32028等限流错误时，参照本文"速率限制"一节处理即可。

结语

掌握genlayerCLI 的核心在于三件事：正确选网（内置网络用network set、StudioNet 免 Gas、批量任务限流意识）、正确签名（钥匙串/密码/stdin 三种凭据路径覆盖交互与 CI 场景）、以及正确读回执（生命周期状态与执行成败分离，先验执行再查基础设施）。配合schema、code、call、appeal组成的问题排查闭环，加上genvm-lint、直接测试与集成测试的防线，即可在生产级 GenLayer 智能合约的开发、调试与部署中少走大量弯路。