Sidiora-Labs/paxeer-monorepo · 上手攻略

仓库：Sidiora-Labs/paxeer-monorepo
链接：https://github.com/Sidiora-Labs/paxeer-monorepo
分类：blockchain / agent / payments / 分布式执行
作者：spark
更新：2026-10-28

版本锚点：仓库 snapshot（2026-10-28）为 544 stars、83 forks、211 open issues，Apache-2.0，主语言 Go。链 chain ID 125，代币符号 paxd，内核守护进程 layerxd（C17）。命令取自 main 分支 README 与 docs/wiki/ 下三篇文档。⚠️ README 明确说明 limited beta 尚未开放，下文详述影响。

一、是什么

这是 Paxeer X Network 的 monorepo——一个"分布式超级状态机（Distributed HyperState Machine）"，README 描述为"为支付、代码执行和意图路由而设计，面向机器及其操作者"。

它有两个执行域：

Paxeer X chain（paxd）：Go 写的链节点，BFT 共识 + EVM 执行层。主包 daemon/paxd，状态机模块在 modules/，RPC 在 rpc/。EVM chain ID 125。
LayerX kernel（layerxd）：C17 守护进程，面向自主 Agent 的确定性执行与记账域。每次 Agent 活动都执行并记账，返回签名回执；layerxctl 是运维 CLI；programs/ 放内核程序运行时。目前是独立守护进程，通过 layerxAnchor 预编译把检查点结算到链上。把内核折叠进链的规范在 spec/layerx-merge/spec.kvx，状态是 draft。

第三块是链上合约与 EVM 预编译面。合约通过 precompiles/ 下的有状态预编译触达原生模块。precompiles/setup.go 注册了 bank、wasmd、json、addr、staking、gov、distribution、oracle、ibc、pointer、pointerview、p256Verify、solo、layerxVerify（0x1012）、layerxCustody（0x1013）、layerxAnchor（0x1014）、layerxExchange（0x1015）、layerxBridge（0x1016）、launchpad（0x1017）、feeToken（0x1018）、xweb（0x1019）。

MergeAddressTable 集合在 v7.0 的 MergeUpgrade 计划中激活：新增 layerxledger（0x101A）、layerxpay（0x101B）、layerxauth（0x101C）、layerxprograms（0x101D）、orob（0x0901）、clearing（0x0902）、oracle aggregator（0x0903）、pofq（0x0904）、scheduler（0x0905）、streams（0x0906）、tee attestor（0x0907）、eip712（0x0908）。v6.12.0 集合（构建在 node/app.go）在该升级激活后提供 perps（0x1015，位于 layerxExchange 之前）、第二代 launchpad（0x1017）、pricefeed（0x1020），及现货集合 spot_pecor、spot_orders、spot_stoporders、spot_quoter、spot_vault（0x1021–0x1025）。

二、解决什么问题

AI Agent 拿钱、拿权限、拿算力，长期缺少统一的记账与结算层。 现有方案各有缺口：链上钱包给 Agent 身份但不解决"谁授权它花了多少"；支付 API 能给 Agent 付款但不提供可审计回执；传统 IAM 能授权但不记账。

Paxeer X 把三件事合成一个执行域：

确定性执行 + 记账：Agent 的每次活动由 LayerX kernel 确定性执行并记账，产出一份签名回执——这是可验证凭证（不是"日志字符串"）。
可编程支付：原生 Asset、LXT20 token、custody credit 充值、HTTP 402 支付，走同一套签名活动机制。
意图路由：链上合约 + 预编译把 Agent 意图路由到链、内核、桥、预言机、launchpad 等目标。

它还解决"谁承担风险"：layerxCustody 预编译（0x1013）做托管，custody proof / layerxproof 做证明，xweb（0x1019）做跨边界通信。README 说得清楚："本地跑通不等于获得部署合约、转移托管、处理真实资产的授权"。

诚实边界：README 技术说明第一句就是——"limited beta 尚未开放"（gateway API 尚不可用），这是运行在真实价值上的 mainnet beta，没有通用水龙头，获批开发者由团队分配测试额度。这意味着：普通开发者今天拿不到可用的公网接入路径。

三、快速安装

工具链要求（版本已核对）

组件	版本	来源
Go	1.25.6	`go.mod`
Rust	1.91.1	`rust-toolchain.toml`
Solidity / Foundry	0.8.27	`foundry.toml`
内核 C 编译器	C17	根 `Makefile`

回放资格测试（replay qualification）额外需要：GCC 13、Clang 18、Docker、amd64 musl runner、以及带 QEMU 的 AArch64 交叉编译器（见 docs/QUALIFICATION.md）。

构建

git clone https://github.com/Sidiora-Labs/paxeer-monorepo.git
cd paxeer-monorepo

# 链节点
make paxeer-build      # 通过 chain.mk 构建 build/paxd
make paxd-build        # 同时构建内核库与程序运行时，并打版本戳
make -f chain.mk build # 直接调 chain.mk target

# LayerX 内核及其工具
make build
make layerxd
make layerxctl

# 各个服务与 workspace
make agent-build
make interop-build
make platform-build
make human-build
make programs-build
make workspace-build   # 以上全部 + 节点 + 根 Foundry 树

测试

make test                  # 内核测试套件
scripts/ci/run-tests.sh    # 内核套件在 -O0 和 -O2 下各跑一遍
make test-contracts
make paxeer-test           # 节点 Go 测试（经 chain.mk）
make paxeer-lint
make agent-test interop-test platform-test human-test programs-test
make bridge-test-evm bridge-test-solana
make ci                    # 公开审计 + 内核测试 + 可复现构建 + 共识符号扫描 + sanitizers
make paxeer-ci             # 节点 lint 与测试
make monorepo-ci           # 所有 workspace：build + test + lint

make public-audit 跑 scripts/ci/public-repo-audit.sh，每次改动都必须通过。scripts/ci/layout-check.sh 与 scripts/ci/vendor-verify.sh 检查目录布局与 vendored 快照。

本地 Beta 集群（当前最现实的上手路径）

因为公网 beta 未开放，本地集群是唯一能完整跑通链、内核、网关、faucet、Agent 的路径：

make platform-beta-cluster-up

它实际执行 bash services/platform/hosted/tests/beta-cluster.sh up $(PLATFORM_BETA_CLUSTER_FLAGS)（up 唯一接受的 flag 是 --boundary-checks）。脚本会：构建镜像 → 起集群 → 签 CA → 生成 secrets → render → apply trusted-boundary → 部署 Paxeer 合约 → 配置身份 → 建端口转发 → 写 env 文件 → 等待 testnet GET /readyz 的 state == "ready"、每个 journey 与 dependency 均 ready == true。

成功后在 stderr 打印 every journey ready: <逗号分隔的 journey 名> 和 environment exported to build/beta-cluster/env。

集群不支持 export 子命令——main 只 dispatch up、down、render、images，其他首参打印 usage 并以 exit 64 退出。只渲染不应用：

bash services/platform/hosted/tests/beta-cluster.sh render
# 打印 rendered manifests under $MANIFESTS_DIR and beta CA under $CA_DIR (nothing applied)

默认端口与端点

端口	服务
19443	testnet
19444	gateway
19445	faucet（私网）
19446	node（pending-core）
19447	agent boundary
19449	Paxeer boundary
19450	developer（webhooks）
19451	identity
19452	Paxeer observer boundary
19453	human（转发到 9443）

kind 集群名默认 layerx-beta。没有 agentd 的端口转发——up 不会启动 agentd。

加载环境变量

up 会写 build/beta-cluster/env（没有单独的 export 步骤），直接 source：

. build/beta-cluster/env

它导出 LAYERX_TESTNET_URL、LAYERX_GATEWAY_URL、LAYERX_FAUCET_URL、LAYERX_TEST_AUTH_TOKEN_FILE、LAYERX_TEST_CA_FILE（build/beta-cluster/ca/ca.crt）、LAYERX_TEST_SOURCE_DID / _PUBLIC_KEY / _KEY_FILE、LAYERX_TEST_DESTINATION_DID、LAYERX_TEST_ASSET、LAYERX_TEST_AMOUNT（默认 1）、LAYERX_IDENTITY_URL、LAYERX_PAXEER_BOUNDARY_URL、LAYERX_PAXEER_SETTLEMENT_CONTRACT、LAYERX_PAXEER_CHECKPOINT_REGISTRY、KUBECONFIG、WEBHOOKS_URL 等。

本地集群 HTTP 调用必须带集群 CA：--cacert "$LAYERX_TEST_CA_FILE"。⚠️ 该 CA 只对它签发的本地集群端点有效，公网 HTTPS 主机用它们自己的部署证书链。

四、核心用法

公共 JSON-RPC

export RPC_URL=https://api-mainnet-beta.paxeer.network/rpc

JSON-RPC 2.0 在 gateway 的 POST /rpc，WebSocket 订阅在 GET /rpc/ws。402LXP 支付序列：challenge → payer grant → settlement receipt → renewal。

示例：

node services/platform/middleware/examples/public-rpc.mjs --help
PYTHONPATH=services/agent/sdk/python python3 services/platform/middleware/examples/public_rpc.py --help

托管 CLI 与密钥

cargo build --manifest-path tools/platform/cli/Cargo.toml
export PATH="$PWD/services/platform/target/debug:$PATH"

layerx key create alice
layerx key default alice
layerx wallet list

OS keyring 是默认存储。无头主机须先配置加密文件存储（见 tools/platform/cli/README.md#headless-credential-storage）才能创建钱包。

⚠️ layerx wallet create 仅限模拟器：它生成密钥、注册 DID 并在模拟器里打开主账户；对公共端点返回 wallet_registration_unavailable 且不生成密钥。wallet import 从标准输入读 32 字节十六进制种子，既不注册也不充值。

充值：custody credit（无公共水龙头）

账户通过已认证的托管信用充值：先向 layerxCustody 预编译（0x…1013，chain 125）存入押金，再基于存款凭证构建 credit，用账户自己的密钥签名活动，最后通过 router 提交。

python tests/bridge/custody_credit.py attest \
  --rpc "$FIRST_RPC" --rpc "$SECOND_RPC" --comet-rpc "$COMET_RPC" \
  --ca-bundle "$CA_BUNDLE" --disposable-identity "$IDENTITY" \
  --profile custody.profile --network-id "$NETWORK_ID" \
  --transaction "$DEPOSIT_TRANSACTION" --beneficiary "$WALLET_DID" \
  --beneficiary-key "$WALLET_PUBLIC_KEY" --expected-amount "$AMOUNT" \
  --output custody.credit

build/tests/bridge/sign-credit custody.profile custody.credit "$WALLET_DID" \
  "$WALLET_KEY" "$WALLET_SEQUENCE" "$TIMESTAMP_MS" funding.activity

jq -cn --arg canonical "$(xxd -p funding.activity | tr -d '\n')" \
  '{jsonrpc:"2.0",id:1,method:"lx_sendActivity",params:[$canonical,"executed"]}' |
  curl --fail-with-body --silent --show-error "$RPC_URL" \
    --header 'Content-Type: application/json' \
    --header "Authorization: LayerX-Key $GATEWAY_KEY_ID:$GATEWAY_KEY_SECRET" \
    --data-binary @- > funding-response.json

幂等性：credit 的幂等键是 custody.credit.nullifier 里的存款 nullifier，重复提交同一笔存款不会二次充值。已签名 credit 只有 5 分钟有效期。

创建与使用原生 Asset

export RECEIPT_POLICY=/absolute/path/to/receipt-policy.json
export FEE_LIMIT='<maximum fee in base units>'

layerx --rpc "$RPC_URL" --gateway-credential beta token create \
  --symbol PAY --name 'Payment Token' --decimals 6 \
  --supply-cap 1000000000 --salt "$(openssl rand -hex 32)" \
  --receipt-policy "$RECEIPT_POLICY" --fee-limit "$FEE_LIMIT" \
  --wait executed

Asset id 的推导公式：SHA-256("LX:ASSET:v1" || issuer_did_id32 || salt32)。

转账前必须先为接收方打开该 Asset 的账户：

layerx --rpc "$RPC_URL" --gateway-credential beta wallet open-account \
  --asset "$ASSET_ID" --receipt-policy "$RECEIPT_POLICY" --fee-limit "$FEE_LIMIT"

layerx --rpc "$RPC_URL" --gateway-credential beta wallet send \
  --to "$RECIPIENT_DID" --asset "$ASSET_ID" --amount 10 \
  --wait executed --receipt-policy "$RECEIPT_POLICY" --fee-limit "$FEE_LIMIT"

提交层级

executed / batched / finalised 三级，决定等多久。写入超时或 pending 时，保留 activity id 查回执，而不是重发写入：

layerx --rpc "$RPC_URL" --gateway-credential beta wallet receipt \
  "$ACTIVITY_ID" --receipt-policy "$RECEIPT_POLICY" --wait finalised

--timeout-seconds 取值 1–300，默认 60。

签名语义

CLI 接受类型化的 SigningRequest，不是任意审批文本。活动披露含活动类型、actor、authority、payer/recipient 角色、transfer 或 spending-limit 金额、Asset、fee limit、not-before/expiry 边界、幂等键、可选 EVM binding 和解码后的 payment。SEND 的 debit 披露另绑定 from、to、Asset、金额、源账户 sequence、幂等键、expiry、context、conditions、授权类型、network 和 protocol。披露会被重新编码并与签名消息摘要比对后才释放签名——改披露、sequence 过期、签名无效、缺 scope、原生回执失败或缺 commitment 证据，CLI 都非零退出。

五、典型适用场景

给自主 Agent 一个能记账的执行层：每次活动由内核确定性执行并产出签名回执，可审计可验证。
机器间支付：Machines 与其 Users 之间的原生 Asset 转账、LXT20 token 发行与转账。
意图路由：合约通过预编译把意图路由到链、内核、桥、预言机、launchpad、perps、现货等目标。
HTTP 402 支付：把"付费墙 + 机器可付"做成协议原生能力。
跨域 Agent 协作：xweb（0x1019）与 layerxBridge（0x1016）处理边界通信与桥接。
可复现构建审计：CI 跑 make ci（公开审计 + 可复现构建 + 共识符号扫描 + sanitizers）。

六、坑与注意

坑 1：公网 beta 未开放，gateway API 现在拿不到

现象：README 说 "The limited beta has not opened yet. The gateway API becomes available when it does." 影响：最大现实约束——没有公网试用路径，所有命令要么指向尚未开放的网关，要么需要本地集群。修复：走本地 Beta 集群（make platform-beta-cluster-up + . build/beta-cluster/env），或申请获批额度。

坑 2：本地集群的 CA 只能用于本地端点

现象：拿到 LAYERX_TEST_CA_FILE 后到处加 --cacert。影响：对公网主机用错 CA 会失败；对本地端点不加则 TLS 校验失败。修复：只对本地集群端点加 --cacert "$LAYERX_TEST_CA_FILE"；公网 HTTPS 主机用其自身证书链。

坑 3：CLI 的 HTTP 客户端不传 CA，30 秒超时是硬编码

现象：本地集群上 CLI 调用报 TLS 错误，以为 CLI 坏了。影响：排查方向被带偏。修复：源码显示 CLI 构造 ureq agent 时设了 30s 超时但无 CA flag（tools/platform/cli/src/http.rs:41-49）。本地集群调用需另处理证书信任；hosted smoke 脚本则显式传 --cacert。

坑 4：忘记先 `open-account` 就 mint 或 transfer

现象：token mint / token transfer 失败。影响：卡在资产流程中间，易误以为是合约 bug。修复：每个 Asset、每个接收方都先 wallet open-account；该命令代表当前选中的本地钱包，准备接收方账户时要选中接收方钱包。

坑 5：sequence 过期导致写入被拒

现象：活动提交后报签名无效或 sequence 错误。影响：反复重试浪费幂等键，且可能重复提交。修复：CLI 用 lx_getSequence([did, "identity"]) 取身份 sequence，源账户 sequence 另行获取。每次写入前重读 sequence，且不要复制上一轮的 canonical bytes——sequence、时间戳、幂等键都绑进签名。

坑 6：写入超时后重复提交

现象：curl 超时，你重跑一遍。影响：重复写入。修复：每次 CLI 调用都会创建新的幂等键。超时或 pending 时保留 activity id 查回执（wallet receipt "$ACTIVITY_ID"），不要重复写。

坑 7：已签名的 credit 5 分钟后失效

现象：先签好 credit，过一会儿才提交被拒。影响：易误以为是权限问题。修复：README 明确 "sign it right before submitting"——临近提交再签。

坑 8：`layerx wallet create` 对公共端点返回 `wallet_registration_unavailable`

现象：以为命令写错了。影响：卡住，且可能误以为本地密钥丢了。修复：这是设计——gateway 不暴露 DID 注册路由。公共身份用 layerx key create + layerx key default。

坑 9：把"本地跑通"当成"有权部署合约或动真实资产"

现象：本地集群全绿，就想直接上主网。影响：触及托管与真实资产的风险边界。修复：README 明确——"A local pass is not authorization to deploy contracts, move custody, or handle real assets." 每次改动须过 make public-audit。

坑 10：目录布局正在迁移中，路径会变

现象：照文档写的路径在新版本上找不到。影响：脚本和 CI 配置失效。修复：README 说明链和内核目录树本版仍在根目录，后续版本会移到 core/ 下（涉及 src、cmd、modules、precompiles、node、rpc 等），programs/ 的 guest SDK 移到 sdk/programs。见 docs/MONOREPO.md。

坑 11：预编译地址在多个升级版本间重排

现象：沿用旧文档的 0x1015 以为是 layerxExchange，实际被 perps 占了。影响：调用到完全不同的功能。修复：README 明确 perps 在 0x1015 且位于 layerxExchange 之前；MergeAddressTable 与 v6.12.0 是两批不同激活时点。用地址前先查 precompiles/setup.go。

坑 12：仓库体积巨大，clone 很慢

现象：git clone 长时间不动。影响：上手体验劝退。修复：仓库 size 约 825 MB（压缩前），含 core/deps/ 里 pin 住的上游库快照。用 --depth 1 浅克隆；快照各带 VENDOR.kvx pin 记录，由 vendor-verify.sh 校验。

七、与同类对比

维度	Paxeer X	Solana	Arbitrum / Optimism	EigenLayer	NEAR
Agent 确定性执行 + 签名回执	✅ LayerX kernel 核心	❌	❌	❌	❌
机器支付协议原生	✅ 402LXP + custody credit	⚠️ 需自建	⚠️	❌	⚠️
意图路由 / 预编译面	✅ 20+ 预编译	⚠️ BPF 程序	⚠️	❌	⚠️
BFT 共识 + EVM	✅	✅	✅（Rollup）	❌（非链）	✅
后量子 / TEE	✅ 有 tee attestor 预编译	❌	⚠️	❌	❌
开放度	⚠️ beta 未开放	✅	✅	✅	✅
许可	Apache-2.0	Apache-2.0	MIT / GPL	MIT	Apache-2.0

和 Solana / Arbitrum：都是 EVM 兼容 + BFT 路线，但它们是通用执行层——Agent 的执行语义要你在程序里自己实现。Paxeer X 的差异是把 Agent 活动做成一等公民：确定性执行、签名回执、内核与链的检查点结算都是内置的。

和 EigenLayer：EigenLayer 做验证者再质押，让服务从多个 L2 借用安全性；Paxeer X 做执行与记账，两者可叠加而非互斥。

和传统支付 API（Stripe / Coinbase Commerce）：它们能给 Agent 付款，但回执是平台数据库记录，不可自验证、不可编程组合。Paxeer X 的回执是签名的、可验证的，且与链上资产一一对应。代价是今天还用不了。

和 x402 协议（Coinbase 提出）：x402 是 HTTP 层的机器支付标准，聚焦"用加密货币付 API 调用费"。Paxeer X 的 402LXP 序列方向一致，但把它放在确定性执行 + 回执 + 意图路由的更大框架里。

八、一句话推荐

如果你在做需要"自主 Agent 能自己收钱、自己签字据、自己路由意图"的系统，Paxeer X 是设计较完整的开源方案之一——Go 链 + C17 确定性内核 + 20+ 预编译 + 签名回执 + 402LXP 支付面，Apache-2.0 且 CI 带公开审计与可复现构建；但它处于 limited beta 未开放、无公共水龙头、目录正在迁移的阶段，公网路径今天不可用，值得关注但请先按本地 Beta 集群评估，不要按"可上线基础设施"做规划。

本文的不确定处（诚实标注）： - ⚠️ 所有命令、路径、端口、预编译地址均取自 main 分支的 README 与 docs/wiki/{Quickstart,PaymentsQuickstart,Getting-Started-Beta}.md，未实际执行（只读研究）。 - ⚠️ 仓库无 release tag 可锚定，因此无法给出确定的运行时版本号；文中版本仅覆盖工具链（Go 1.25.6 / Rust 1.91.1 / Solidity 0.8.27 / C17）。这与 precompiles 依赖 v6.12.0 / v7.0 升级计划的引用形成对照，说明仓库版本体系与文档版本体系不一致。 - ⚠️ 预编译地址表（0x1012–0x1019、0x101A–0x101D、0x0901–0x0908、0x1020–0x1025）来自 README 对 precompiles/setup.go 的描述，未逐一对照源码行；README 自述 MergeAddressTable 位于 precompiles/setup.go:66-79，未核实当前 main 分支实际行号。 - ⚠️ 端口表、env 变量名、beta-cluster 脚本行号引用（如 beta-cluster.sh:3598-3743）为文档原文引用，未核实行号是否仍匹配当前 main。README 自述目录树将移入 core/，行号极可能已漂移。 - ⚠️ layerx CLI 子命令集（key / wallet / token / install）从文档拼出，未从 tools/platform/cli 源码校验完整参数签名。 - ⚠️ 未核查：docs/QUALIFICATION.md、docs/MONOREPO.md、spec/*.spec.kvx、docs/wiki/{Custody,Cli,Programs,PublicRpc}.md 的具体内容（仅确认路径存在于仓库树），可能含本文未覆盖的关键细节。 - ⚠️ star/fork/issue 数为 2026-10-28 经 GitHub API 读取的快照。仓库创建于 2026-08-14，历史仅约两个半月，生态成熟度需持续观察。 - ⚠️ Sidiora-Labs/Paxeer-X-Network 是另一个仓库（知识库中已有其攻略），与本 monorepo 的关系与差异未核实。