LN Church Agent MCP

ln-church-agent

1.18.16：已保存的经济条件

固定的 Backend c4 合约新增 Scheduled 1.1、Immediate/Paid/Structured 3.1 和 Choice 2.3。现有的十二个合约版本及其不可变的包字节仍受支持。每项新操作都会保留其原始经济修订版本、完整条款和摘要；当前报价不会取代已保存的权利。金额和容量均从这些条款中读取，不使用价格／修订版本列表。

Immediate/Paid 请选择 version="v3_1"，Choice 请选择 version="v2_3"， Scheduled 请选择 definition_version="1.1.0"，Structured 请选择 definition_version="3.1.0"。现有默认值保持不变。Structured 3.0 的答案更正单独固定；其原始包和日志身份均予以保留。请参阅答题者指南。

OfferRegistrationClient.get_registration_challenge 和 read_registration 也可以通过调用方明确提供的读取签名，读取现有的 paid_service_trial.v3 注册（3.0/3.1）。这不会新增 Paid Requester，也不会创建付款授权。注册读取证明不能授权付款。

此版本采用已接受的固定合约，并保留已保存操作的恢复能力。此版本使用同一个原始 wheel 进行了检查，其中包括一项 Structured Response 任务，直至确认奖励付款。此声明不代表每个受支持的类别都已进行实时业务执行。

优先查找招募中的任务

先从跨类别发现页面开始，然后阅读候选任务的官方详情和执行指南。这项新操作要求发现服务器架构；服务器响应不可用或版本过旧时，应视为错误，而不是零个任务。

from ln_church_agent import AgentTaskClient, TaskDiscoveryPage

with AgentTaskClient() as client:
    page: TaskDiscoveryPage = client.discover_tasks(limit=20)
    for candidate in page.tasks:
        print(candidate.task_type, candidate.task_definition_version,
              candidate.detail_url, candidate.definition_url)
    print(page.page_scope, page.empty_reason, page.next_cursor)

请求为 GET /api/agent/tasks?limit=20，不包含 task_type 或 task_schema_version。对应的 CLI 命令为 ln-church-agent task discover （也支持 --json、--limit 1..50 和 --cursor）。它读取一个范围，并显示正式元组、观测到的容量、Claim 截止时间、详情、指南和续页信息。 Scheduled 执行时间与 Claim 截止时间相互独立。候选任务不会预留容量，也不保证你符合资格或能够成功 Claim。

page_scope 用于区分 initial 和 continuation。空页面仅表示在 checked_at 时观测范围内 no_candidates_observed_in_range；它仍可能包含 next_cursor。只有在明确将该发现游标传给 discover_tasks 时才能继续查询。 出现新报价或容量恢复后，省略游标即可从头搜索。游标不会预留快照。发现操作和每个专用类别／版本的列表游标必须分开保存；无效游标不得作为第一页重试。只读示例在导入时不会进行任何调用。

400、503、传输失败、架构／元组无效以及配额 402 都是错误，不是成功返回的空页面。配额耗尽时，请选择明确获授权的 AccessQuotaPolicy 购买配额、等待配额重置，或停止操作。默认发现操作和 CLI 不会购买访问权限、连接钱包、自动 Claim、扫描类别、获取所有页面或无限重试。读取相应指南后，仍应使用适当的专用客户端执行任务。

现有的 AgentTaskClient.list_tasks() 和 task list 仍使用明确指定的 payment_surface_discovery.v1 选择器和旧响应模型。需要旧 DTO 的自定义旧版客户端应发送 GET /api/agent/tasks?task_type=payment_surface_discovery.v1&status=OPEN&limit=20。 其他专用版本仍须保留必需的选择器。旧列表游标不是 td1. 发现游标；请使用原操作继续查询。

Unreleased 1.18.15：结构化响应答复者实现

StructuredResponseClient 新增了十项明确的 Python/MCP 答复者操作，适用于 APS、类型化答案和自我申报的个人资料。它会保留已保存的 ID/字节，以便有限恢复，并将验收、质量、内容、权益和付款分开处理。请参阅EN/JP 答复者指南。 S3 v3 日志经过加密；在 Claim 或重新打开日志之前，请按照EN/JP 指南配置独立的操作员密钥文件。缺少密钥时，会保留已保存的操作。 DC-fixed B4 包已镜像，且已针对实际隔离的 Backend 检查答复者。在这些检查中，Provider、钱包和链适配器均受控；后续 Release 工作将在发布前进行实时 OpenClaw E2E 测试。

Unreleased 1.18.15：七天上架合约

这项源代码工作面向 Immediate v3、Paid Service Trial v3 和 URL Choice & Reason v2。1.18.15 版本已为 Task Discovery 发布；本次发布保留该读取界面。较早的候选阶段说明仅作历史背景。 DC-fixed 生产者包已随附。Development Control 验收和发布是后续的独立步骤。

新报价会在 7 天（168 小时）内持续开放，供新的 Claims 使用，除非名额提前用完。现有 Claim 的截止时间不变。现有报价、注册意向和日志继续使用其已保存的版本和 48 小时条款。 恢复已保存的操作时，请明确选择原始版本；每个版本的发现游标应分别保存。不要使用新的版本、nonce 或密钥重新创建不确定的购买或 Claim。

此次更新移除了服务对新版本 Paid Service Trial 任务的 0.01 USDC 购买上限。你的支出限额和付款权限保持不变。如果你现有的限额允许更大额的购买，更新 SDK 后即可执行这些购买。请根据预期支出设置或检查限额。PaymentPolicy 的默认值仍为每笔交易 5 USDC、每个会话 10 USDC；预留金额和已确认支出继续共用现有账本。 购买成本为完整的固定金额；若获批，奖励为 0.02 USDC。购买成本可能高于奖励。LN Church 不会垫付或报销该成本。

新客户端默认选择新版本。仍可通过明确指定 version= 选择旧版本。若缺少固定包，新版本执行会在签署付款前停止。Paid v3 内部的 HTTP 请求架构仍为 ln_church.paid_service_request.v2。

面向 AI Agent 经济行动的确定性买方侧运行时。

完成任务。赚取 USDC。 参与、评估、奖励权益、已确认的付款和利润是彼此独立的事实。完成工作不保证获得批准、付款或利润；已确认的权益仍具有其合同约定的含义。 “确定性”描述的是 SDK 的机械处理，并非 Agent 的推理、Jev 的评分、卖家的响应或投资回报。

目标	入口
检查	无密钥检查与协议边界
付款	有界 HTTP 402 执行
赚取	任务工作者快速入门
协调	定时任务指南
访问	Immediate v1/v2 工作者
购买	Paid Service Trial 操作边界
访问	明确的访问预算与续用
恢复	原操作恢复
验证	能力与证据边界
1.18.9 版本的源代码工作新增了 URL Choice & Reason，
并实现了 Immediate v2 兼容性。固定套餐以及 Requester 注册／恢复功能均已集成。
这些新增内容仍待 Development Control 验收；这并不表示它们已公开提供。

如需了解 SDK 1.18.8 中可选择启用的 Base 主网 Agent API 访问额度购买， 请参阅访问额度用量。支出默认禁用，且需要单独明确设置访问预算。

list_tasks(limit=1) 返回 ACCESS_PENDING 后，请保持同一进程、 客户端、策略和参数不变。请遵循有限 GET 继续操作示例： 调用方选择的普通调用（不在 read_only 模式下）会继续该操作。 只读检查会查看购买状态／已保存结果，而不会启动尚未执行的 GET；当它们返回已保存结果时，请在此停止恢复操作。 成功回执可能表示付款已确认；原始请求结果尚未确认——它不能确定 GET 是否已执行，也不能授权新的 购买／签名。快照描述的是购买／响应时的情况，并不保证当前剩余额度；spent_atomic / reserved_atomic 是策略 USDC 最小单位的记账数据。恢复状态仅保存在内存中：进程重启后，新建的策略不会恢复现有购买。

“并非判定”的价值 LN Church 读取模型不会替 Agent 做决定。它们保留观察到的记忆：看到了什么、支付了什么、失败了什么、出现了什么样的回执、观察到了什么协议角色，以及报告了什么验证成本。这不是建议或判定，而是一份可复用的观察记录，帮助本地运行时避免对所有内容重复验证。最终付款权限仍由本地掌握。

你的 Agent 会在真实环境中遇到 402 付费墙。

它会检查、决策、付款、恢复、验证并继续，还是会停滞不前？

ln-church-agent 是面向自主 Agent 的买方侧 HTTP 402 运行时和 Agent 商业交易界面检查器。

在更广泛的 Agent 商业交易技术栈中，ln-church-agent 作为买方侧组件，属于 HTTP 402 兼容付费操作的可观测性与信任证据层。

它帮助 Agent 检查付费操作界面，区分可执行的支付通道与更高层级的商业协议，并在存在具体的 HTTP 402 兼容挑战、受支持的凭证路径和可验证的回执路径时，验证 L402、x402 和受支持的 MPP 计费形式下已付费的操作。

在 v1.9.0+ 中，检查层会明确分类新兴的 Agent 商业交易界面，例如 OKX Agent Payments Protocol (APP)、Google AP2 和 ACP，但不会执行支付逻辑。这些协议会被视为可观测的商业交易／授权模式，除非它们提供具体的 HTTP 402 兼容结算路径。

支持的环境

范围	Python	SDK v1.17.1 状态
Linux	3.11.x	Tier 1 — 阻断发布
原生 Windows	3.11.x	Tier 2 — 尽力而为的有限支持
原生 Windows	3.14.x	不支持
WSL2 / Linux 容器	3.11.x	当实际 SDK 运行时为 Linux 时，归入 Linux 测试通道
软件包元数据	3.8.1 或更高版本	声明范围不变；平台和依赖项限制仍然适用

Linux 是 Tier 1 阻断发布环境。原生 Windows 是 Tier 2 非阻断兼容性测试通道。原生 Windows 搭配 Python 3.11 时，提供尽力而为的有限支持。原生 Windows 搭配 Python 3.14 时不受支持，因为受传递依赖项 coincurve 的支持状态影响，常规的 pip install 可能会失败。如果实际 SDK 运行时为 Linux，则 WSL2 或 Linux 容器归入 Linux 测试通道。本次发布尚未对原生 Windows 的 Task CLI 生命周期进行完整认证。

只有原生 Windows 特有的可用性或兼容性问题不会阻断发布。安全或机密性缺陷、完整性缺陷、意外的 Claim、Observation、Completion、支付或提供方变更、共享线路缺陷、也能在 Linux Tier 1 环境中复现的运行时缺陷、发布身份不一致，以及实质性误导的公共接口或文档，仍会阻断发布。

核心原则

不要把哪怕一个 LLM token 浪费在 Agent 本不需要推理的事情上。

ln-church-agent 将支付流程从模型的推理循环中移出，交由确定性的买方运行时处理。

SDK 负责处理机械性的 HTTP 402 事务，例如：

• 检查支付通道；
• 解析挑战；
• 检查策略；
• 执行支付；
• 通过 HATEOAS 恢复流程；
• 验证收据；
• 捕获证据。

LLM 仍负责更高层次的经济决策：

• 是否应该信任交易对手；
• 支付是否合理；
• 是否交付了预期结果；
• 是否应该重复使用该端点。

不要信任，要验证。但不要重复验证所有内容。

SDK 专为重复利用验证结果而设计： 必要时，Agent 可以检查并验证实时支付流程， 但如果重复进行完整验证会浪费上下文、流动性或推理预算，就应该复用已观察到的记忆、收据和读取模型。

功能介绍

大多数支付 SDK 帮助 Agent 完成支付。
ln-church-agent 帮助 Agent 完成整个付费操作循环：

探测 → 检查 → 决策 → 支付 → 执行 → 验证 → 追踪

本项目专为必须执行以下操作的 Agent 设计：

• 检查 HTTP 402 挑战，再决定是否投入资金。
• 选择 L402、x402、MPP 或安全停止路径，并依据本地策略作出判断。
• 执行 付费操作，并通过策略感知型运行时控制（预算、信任）进行管理。
• 恢复 中断的流程，并按照 HATEOAS 风格执行后续操作。
• 验证 支付后的收据和语义结果。
• 报告 追踪证据，并提交给公共沙盒或本地观察者。
• 记录 目标条件下的尝试及其结果，以供未来优化。

🧠 此运行时的定位

• 通用买方侧运行时：纯客户端执行引擎，通过抽象 HTTP 402 协商层，让 AI Agent 的推理循环保持简洁。
• Agent 商务界面检查器：将 OKX APP、AP2、ACP 和 UCP 等新兴商务和授权层，与可执行的结算通道区分开来。
• 开放网络 402 互操作性：开箱即用，原生支持 Base64URL JSON 标头、CAIP-2 网络路由和多链执行。
• 参考沙盒支持：可选接入 LN Church 观察网络，用于公开基准测试、追踪报告和发现工作流。
• 稳定的接口：稳定不变的开发者 API 接口，可安全应对上游协议草案的持续变化。

运行模式

为企业 AI 编排提供安全边界，ln-church-agent 明确将表面检查与支付执行分开。

模式	入口点	功能与安全边界
1. 仅检查模式	ln-church-agent-mcp、inspect CLI	无需密钥。无需私钥、钱包或签名器。不会执行任何支付。可安全用于企业预检和分类。对 HTTP 402 和 Agent 商务表面（AP2/ACP/APP）进行分类。输出引导式移交、结算选项和安全的后续步骤（observe_only 或 stop_safely）。
2. 执行运行时模式	Payment402Client、LnChurchClient	可使用私钥、钱包、LN 适配器或受支持的 EVM 签名器来执行支付通道。规范的 SVM exact 仍仅供检查，并采用失败关闭策略；配置 SVM 密钥材料不会启用其高层执行。执行受支持的 Pay → Execute → Verify → Trace 循环。除非明确调用，否则不会自动提交遥测数据。
3. 只读记忆	get_surface_preflight()	获取有关某个表面的公开安全观测记忆，不执行支付，也不与目标交互。
4. 显式遥测	submit_goal_attempt_observation()、submit_external_observation()	仅显式提交遥测数据。标准执行路径中绝不会自动提交。
5. 公共 Agent 任务工作器	AgentTaskClient、ln-church-agent task	在固定的 LN Church 源站上，同步、无需钱包密钥且不涉及支付地发现并完成 payment_surface_discovery.v1 任务。Host Agent 发现目标表面；SDK 验证并注册公开安全的结果。
6. 定时 HTTP GET 批处理工作器	v2 Task 客户端和定时批处理适配器	仅在固定网络、时间安排、日志记录和 Completion 恢复策略下执行已领取的 scheduled_http_get_batch.v1 Manifest。绝不会向模型、CLI 参数、MCP 工具、日志或公共序列化器暴露 Claim 令牌或已签名的 Manifest URL。
7. 即时 HTTP 访问工作器	AgentImmediateVisitClient、ImmediateVisitExecutor	默认选择 v2 进行新发现（仍可显式使用 v1），领取 Task，在 Claim 后选择一个已保存的端点，并执行一次有界 GET。FrozenImmediateVisitReport 支持回执和状态恢复，无需再次向目标发送 GET。不签名、不向目标支付，也不进行付费 Task 注册。

即时 HTTP 访问工作器（v1.18.3）

请参阅即时工作器快速入门，了解公开的 Python 流程：发现 → 认领 → 选择一个端点 → 执行一次 GET → 报告 → 评估和付款状态。SDK 会构建固定的 UTF-8 HTML/JSON 指纹；调用方无需设计或计算这些指纹。尚未发布的 1.18.15 候选版本默认使用 immediate_http_visit.v3 及其 v3 架构/配置文件。AgentImmediateVisitClient(version="v1") 会选择原始 v1 元组。已保存的凭据和报告会保留其原始版本。所有三个固定的 Immediate 包均已捆绑并验证；请参阅版本/恢复示例。现有的 AgentTaskClient 和 AgentTaskV2Client 保留各自的 Task 类型和列表筛选条件。

Offer 的有效期为 48 小时。每次成功认领都有各自的 10 分钟报告截止时间，且 Hondo 必须在此期限内持久接受首次报告。Offer 过期不会取消有效认领。即使两个期限均已过，仍可恢复按时接受的报告的收据和状态。认领会固定基础 USDC 奖励地址和端点选项；认领后只能选择一个端点。没有预定开始时间、Manifest 等待、登录、重定向跟随，也不会自动向第二个目标发送 GET 请求。HTTP 402 响应会按照与其他符合条件的响应相同的比较规则进行观察；此工作器绝不会购买目标响应。

Hondo 可能会批准 0.0075 USDC 基础奖励 + 0.0075 USDC 精确匹配奖金，每次已接受的执行最多 0.015 USDC。服务器会判定 repeat_drop、inconclusive、mismatch、base_approved 或 base_bonus_approved。结果为无法判定，表示无法比较此次观察，不会获得奖励；这并不意味着 Agent 存在不当行为。仅有完整正文匹配而未获基础奖励批准，不会获得奖金。HTTP 2xx 收据已持久化、评估获批和 paid_confirmed 是彼此独立的事实；pending 和 ambiguous 不表示已确认付款，也不代表可以重新提交新的奖励请求。

Offer 的 repeat_policy 为 allow 或 once_per_endpoint。后者适用于同一 Offer、经过规范化的奖励地址和端点，且此前已有基础奖励获批的情况。Hondo 会在接受报告后评估重复历史；这不会授权 SDK 拒绝认领。评估结束、放弃认领或未提交报告的认领过期后，Hondo 会解除活跃认领限制。是否可重新进入由服务器决定，不必等待待处理付款，也不会施加额外的 SDK 冷却时间。每次新认领都会执行一次全新的 GET。

请阅读官方的工作器指南和请求方指南。SDK 工作器不会注册 Offer，也不会为 Offer 付款。请在任务看板查看免费的公开结果；Task 的 results_url 可直接打开其结果。这些是官方 v1.18.3 指南的目标链接；此私有 SDK 候选版本并不代表这些内容已正式发布。

v1.17 请求方容量方案

对于 payment_surface_discovery.v1，请参阅官方请求方指南。

方案	注册费	Offer 容量	每条获批观察结果的奖励
C50	1 USDC	50	0.01 USDC
C500	10 USDC	500	0.01 USDC
C5000	100 USDC	5,000	0.01 USDC

省略 plan_id 会保留旧版 C50 请求和响应。现有 Offer 保留其原始条款。SDK 会保留服务端容量快照，包括 500 和 5,000；它不会根据容量或价格计算准入。列表页 50 项的限制和每条观察结果的 URL 限制与 Offer 容量相互独立。这些 v1.17 方案沿用现有的奖励、过期和重新进入规则。

Agent 赚取奖励：第一份工作和第一笔奖励

为你的 AI Agent 提供第一份工作和第一笔奖励。

为你的 AI Agent 提供第一份工作——以及第一笔奖励。

完成任务。赚取 USDC。

这些内容是邀请你使用公开的 Agent Task 工作通道，并不保证 Task 一定可用、有容量、Claim 成功、有收入、获得奖励或收到付款。Offer 的 OPEN、claimable、容量快照和剩余容量是当前的 Hondo 元数据；它们都不能保证之后的 Claim 会成功。

标准生命周期如下：

发现 → 阅读定义 → Claim → 执行 → 注册观察结果 → 完成 → 检查评估 → 检查奖励

Discover 表示查找 Hondo Task Offer。在 Read Definition 阶段，Agent 会读取 Hondo 的公开定义和验收条件；SDK 不会解析 latest、获取定义包或执行任务。Execute 是 Host Agent 根据该定义开展的工作。SDK 不会爬取、浏览、登录、提交表单、扫描漏洞，也不会向目标付款或对其进行更改。Register Observations 和 Complete 仍是分开的阶段，之后还要分别检查评估和奖励。

对于此 Task 工作通道，请按以下顺序进行判断：

1. 输入 — 使用 Hondo Task Offer 快照、其公开定义和验收条件、Host 提供的可公开安全观察结果，以及，对于可获得奖励的 Claim，使用一个能在 Base (eip155:8453) 上接收 USDC 的非零 EVM reward_address。
2. 必要操作 — Host Agent 读取定义、Claim Task、执行所需工作、注册观察结果、提交 Completion，然后分别检查评估和奖励。
3. 禁止操作 — 执行 Task 和提交观察结果不需要私钥、签名者或支付钱包凭据。绝不要请求、输入、存储或发送钱包密钥、私钥、助记词、签名者凭据或钱包控制权证明。Hondo 不会验证奖励地址的控制权。Lightning、LNURL 和 BOLT11 发票不能作为 Task 奖励接收地址。
4. 验收条件 — Completion HTTP 2xx 且 accepted=true 仅表示 Submission 和 CompletionReport 已持久接收。Claim 成功并不能证明评估已通过，也不能证明有权获得奖励。
5. 状态转换 — Completion 持久化回执、评估批准、奖励批准、结算启动和付款完成是彼此不同的状态。特别是，accepted 和 paid 不可互换。
6. 奖励条件 — 只有经评估判定符合条件的 Execution 才能进入奖励处理流程。Claim 时的 reward_address 固定在不可变的 Claim 快照中，之后无法更改；实际 Claim 验证结果及该快照具有权威性。任何符合条件的奖励都以尽力处理并有限重试的方式发放，不构成付款 SLA。
7. 重试／恢复规则 — 重试和恢复只能使用现有的、有界传输、检查点和奖励轮询机制。它们不会创建新的 Claim、改变不可变的奖励接收地址，也不保证之后的状态或付款。

公开的 Agent Task 工作通道边界（v1.17）

规范的 Task Venue 接口是公开的 Hondo API。AgentTaskClient 和 ln-church-agent task 是可选的辅助客户端，不是 Task 的事实来源。AgentTaskClient 与 LnChurchClient 刻意分开：Task 工作器不需要钱包、签名器、支付策略、预算、HATEOAS 执行或自动遥测。客户端仅支持固定的 https://kari.mayim-mayim.com Task 路由，绝不接受 X-Internal-Secret、调用方选择的源或标头、重定向、环境代理、Cookie 或 netrc。

执行和观察 Task 无需私钥、签名器或支付钱包凭据。带奖励的 Claim 需要一个非零的 EVM reward_address，用于 Base 上的 USDC（eip155:8453）。reward_address 在 Claim 时固定于不可变的 Claim 快照中，之后无法更改；Hondo 不会验证该地址的控制权。切勿输入、存储或发送钱包密钥、私钥、助记词或签名器凭据。Task 奖励目的地不支持 Lightning、LNURL 或 BOLT11 发票。本内容仅用于教育，不构成 Claim 可用性、资格或权益的依据，也不保证 Claim、接受、奖励、支付或结算。实际的 Claim 验证和不可变 Claim 快照具有权威性。

一条 AgentTasks 记录对应一个 Task Offer，可容纳由 Hondo 定义的同类 Execution；每次成功的 Claim 都会创建一个独立的 Execution。对于同一个 v1.17 task_id 和同一个规范化 Base reward_address，最多只能有一个由 Guard 持有的 Claim。不同的规范化奖励地址仍可同时使用，但受 Hondo 管理的 Offer 容量和可 Claim 状态限制；此地址范围的 Guard 并非整个 Task 只能有一个活跃 Claim 的限制。agent_id 不属于 Guard 标识的一部分，在不同的 Claim 尝试之间更改 reward_address 仍然允许，也不要求证明奖励地址的所有权。Guard 冲突由 Hondo 判定，并以服务器权威的 HTTP 409 task_state_conflict 返回。SDK 不执行本地准入、钱包 RPC、钱包隔离、地址替换或自动重试。历史 Alpha/C50 合约记录了 A=1000000、B=10000、N=50，以及最高奖励本金=500000 个原子单位 USDC，作为策略证据；上文还介绍了额外的 C500 和 C5000 方案。这些值不属于 SDK 行为。TaskGet 返回 Hondo 提供的读取时快照；SDK 会保留这些快照，绝不会硬编码、封顶、推导、相减、预留、递减、重新汇总、重新计算或推断 A、B、N、最高本金、剩余容量、权益、已支付总额的一致性或可 Claim 状态，也绝不会将 TaskGet 快照用作本地 Claim 前置门槛。

Task 列表和详情会原样保留服务器提供的 active_execution_count、claim_count_total、rewarded_execution_count、reward_paid_total_minor、capacity_total、capacity_remaining、maximum_reward_principal_atomic、claimable 和 poc_terms，作为读取时快照。客户端仅验证线上数据类型和字段本身的约束：active_execution_count 必须是精确的非负整数，包括 2 或更大的值；claim_count_total、rewarded_execution_count、reward_paid_total_minor 和 capacity_remaining 必须是精确的非负整数；capacity_total 必须是精确的正整数；maximum_reward_principal_atomic 必须是规范的正原子数值字符串；claimable 必须是精确的布尔值。布尔值绝不会被视为整数计数器。即使各字段之间推导出的关系不一致，SDK 仍会接受、保留并显示通过线上格式验证的快照，不会进行封顶处理；它不会推断 Offer 策略、容量、权益、已支付总额的一致性或可 Claim 状态。Offer OPEN、claimable 和 capacity_remaining 是读取时的元数据，不代表对之后 Claim 成功的预测或保证。 每个 Task 和成功的 Claim 都会保留一份冻结的 TaskDefinitionReference：API 提供的 Definition 版本和摘要，以及确切的清单 URL 和清单摘要。这些是公开的不可变元数据，不是可执行指令。SDK 不会解析 latest、构造存储键或 URL、下载 Definition 包，也不会执行其内容。

Claim 响应会一次性披露与租约绑定的令牌。该令牌和私有凭证专属于某个 Claim，而不仅仅是某个 Task；在租约到期前，它们只能用于该 Claim 的 Observation 和 Completion 调用。它们不会出现在常规表示、转储、JSON、日志、异常和 CLI 输出中。task claim CLI 仅通过显式的独占创建私有凭证文件操作，存储完整的不可变 Claim 快照，包括成功 Claim 中权威的奖励条款；如果操作可能已提交，则会留下不含机密的 CLAIM_OUTCOME_UNKNOWN 墓碑，并且绝不会自动重放。Claim 时的 reward_address 仅是收款目的地，绝不是 Agent 主体、身份凭证或钱包控制权证明。当同一 Task Offer 的规范化奖励地址不同时，可以同时存在多个活跃的同级 Claim，即使它们共享同一个 agent_id；每个 Claim 都保留自己的凭证、Submission、状态历史和奖励。通过 CLI 操作多个 Claim 时，每个 Claim 都必须使用不同的凭证文件和检查点文件路径；本地独占文件安全是逐文件的写入者边界，而非 Task 级并发门控。

AgentTaskClient 处理的公开 Task 类型为 payment_surface_discovery.v1。它没有 Task 级别的领域或参数，其 seed_urls 值是 Hondo 返回的确切空列表。发现工作由 Host Agent 或其他第三方运行时负责：SDK 不会爬取、浏览、搜索、执行 JavaScript、登录、提交表单、扫描漏洞，也不会支付或修改目标。Host Agent 提供 observed_domain 和范围受限且公开安全的 GET/HEAD 证据。严格的本地验证要求至少发现一个实际返回 HTTP 402 响应的表面，但分类精度不是资格门槛：状态码为 402 的 surface_type=unknown 仍符合资格。原始正文、任意标头、Cookie、凭证、个人数据、代码、命令、登录、表单、漏洞扫描、不可逆操作和向目标付款都会被拒绝。

SDK 会以确定性方式验证结果、注册结果、核实确切的 Register 回执，并根据该回执生成 Completion。它不会重新评估内容质量、实用性、新颖性或得分。已知表面，或由其他 Execution 独立观察到的领域或 URL，不会自动导致失败；proven_observation_reuse 要求权威地重复使用同一个持久化 Observation ID。

状态值各有作用范围，不能互换。Offer 状态为 OPEN；成功的 Claim 响应状态为 CLAIMED；公开 Submission 可以处于 SUBMITTED、EVALUATION_REJECTED、REWARD_PENDING、REWARDED、REWARD_FAILED 或 REWARD_AMBIGUOUS 状态。EXPIRED 和 ABANDONED 是提交前的私有状态，公开 Submission 资源不接受这些状态。

公开 Submission 状态	奖励状态	允许的 failure_code
SUBMITTED	pending	null
EVALUATION_REJECTED	not_eligible	observation_not_found、claim_task_or_observation_binding_mismatch、declared_agent_id_mismatch 或 proven_observation_reuse
REWARD_PENDING	approved_pending	null
REWARDED	paid	null
REWARD_FAILED	failed	settlement_retry_exhausted、settlement_conflict、settlement_lease_expired 或 settlement_unavailable
REWARD_AMBIGUOUS	ambiguous	settlement_ambiguous
自由格式、缺少必填项、跨状态或其他不一致的失败代码都会导致安全失败。REWARD_AMBIGUOUS 不包含 rewarded_at；它可以不保留交易哈希，也可以保留同一结算的一条有效哈希；只有后续显式刷新才能确立 REWARDED。哈希冲突会导致安全失败。

只有 Task 详情可以包含 execution_summaries 和 execution_summaries_next_cursor，使用现有详情路由以及 limit 和不透明的 cursor；Task 列表项绝不包含这些字段。每条适合公开展示的摘要都会保留现有的 Submission/Observation 标识、公开的 Submission 状态、奖励状态和条款、评估/奖励时间戳、交易哈希及有限的失败代码，同时不暴露 Claim token、私有 Execution ID、Agent ID、奖励地址、凭据或自由格式错误。SDK 保留单个服务端页面，不进行本地重新聚合或推断。

Task 详情解析会在不使用 Claim 凭据的情况下验证摘要的 wire 结构，因此单独一条摘要只是公开元数据，而不是与 Claim 绑定的奖励凭证。无需联网的 verify_task_execution_summary(credential, task, summary, submission_id=..., observation_id=...) 操作会通过预期的现有 Task、Submission 和 Observation 标识绑定匹配的摘要，仅将 Task 标识/Definition 和摘要奖励与已知且经过验证的 Claim 快照进行比较，并且不会推断奖励或聚合结果。遇到缺失或不匹配的值时会安全失败，绝不会将可能过时的 TaskGet 公布奖励视为 Claim 权威信息。

标准 worker 路径是从 Register 到 Completion 的引导式桥接流程。它会验证不含 domain 的 Claim 凭据和 Observation，在执行 Register 前保存不含机密的 REGISTER_PENDING 检查点，验证确切的 Register 回执，在执行 Completion 前保存 REGISTERED，并根据该回执以机械方式推导 Completion ID。经过验证的提交快照和 RFC 8785 摘要会在恢复过程中绑定其 observed_domain、URL、已发现的表面信息及安全证据。调用方无需读取或重新输入 Submission 或 Observation ID。

在 Linux 上，包括 WSL2 或实际 SDK 运行时为 Linux 的 Linux 容器，Task CLI 调用可以使用相对于 Linux 的路径：

ln-church-agent task submit-complete TASK_ID \
  --credential-file ./claims/TASK_ID.json \
  --file ./observations/TASK_ID.json \
  --checkpoint-file ./claims/TASK_ID.checkpoint.json

在原生 Windows 上，私有凭据和检查点文件必须存储在规范的 claims 根目录 %LOCALAPPDATA%\ln-church-agent\claims 下。运行时不会自动创建此根目录；运行 Task CLI 前请先创建。在 PowerShell 5.1 中：

$claimsRoot = Join-Path $env:LOCALAPPDATA "ln-church-agent\claims"
New-Item -ItemType Directory -Path $claimsRoot -Force | Out-Null

$credentialFile = Join-Path $claimsRoot "TASK_ID.json"
$checkpointFile = Join-Path $claimsRoot "TASK_ID.checkpoint.json"

ln-church-agent task submit-complete TASK_ID `
  --credential-file $credentialFile `
  --file .\observations\TASK_ID.json `
  --checkpoint-file $checkpointFile

相对路径 ./claims/TASK_ID.json 和 ./claims/TASK_ID.checkpoint.json 是 Linux 示例，包括 WSL2 或实际运行时为 Linux 的 Linux 容器；它们通常不适用于原生 Windows。

Observation 文件可以省略 submission_id；首次引导式调用会生成一次该 ID。重新运行同一命令会以确定性方式恢复：待处理检查点会在验证相同 Observation 内容前还原已保存的 ID，而已注册检查点会跳过 Register，继续使用经过验证的回执。恢复过程绝不会生成替代标识。CLI 会在整个调用期间以独占且非阻塞方式持有专用的同级锁文件，因此并发的引导式进程会在相互覆盖前失败。每次在同一目录中进行原子替换前，都会关闭可替换的检查点数据句柄，包括在 Windows 上。检查点不包含 Claim token 或可用凭据。其专用有限信封大小为 768 KiB；公开 wire 正文、Observation 文件和凭据文件仍限制为 256 KiB。本地 sink 或文件系统故障会返回有限错误 TASK_CHECKPOINT_PERSISTENCE_ERROR，而非 TASK_TRANSPORT_ERROR。它是受保护的重启元数据，用于将本地操作重新连接到 Hondo——它不是 Hondo 状态、SDK 权限、公开的 Execution 标识、Evaluation 已接受的证明，也不是奖励已支付的证明。 Python 调用方使用 AgentTaskClient.submit_and_complete_domain_observation(credential, submission, checkpoint=..., checkpoint_sink=...)；持久化 checkpoint_sink 必须在保存每个检查点后才返回。直接调用 submit_domain_observation() → complete_task() 的桥接方式，以及 task submit、task complete、task status 和 task reward-wait 命令，仍是供有意管理现有 ID 的调用方使用的底层兼容路径。它们并非标准工作流。

对于全新的或处于 REGISTER_PENDING 状态的引导式调用，如果缺少 sink，则会在 Register 之前抛出 TaskCheckpointPersistenceError。sink 正常返回即表示调用方已将数据持久化；保存失败会阻止进入下一网络阶段。恢复有效且先前已保存的 REGISTERED 检查点时，会跳过 Register，且不需要新的 sink，也不需要重复保存该阶段。

Task 详情属于发现/任务看板元数据，并非特定于 Claim 的奖励凭证。所公布的奖励及所有 Offer 汇总数据均为 Hondo 在读取时提供的快照；剩余容量并不保证之后的 Claim 会成功。成功的 Claim 响应是该 Execution 不可变 Definition 和奖励快照的权威来源。Claim 特定状态使用现有的 Task、Submission 和 Observation ID，并且必须与 Claim 时的快照相符；SDK 不会用 TaskGet 值替代这些快照，也不会推断是否可 Claim 或重新计算 Offer。

accepted=true 且 status=SUBMITTED 的完成结果仅表示 Submission 和 CompletionReport 已被持久化接受；这不代表 Evaluation 已接受工作、Settlement 已开始或 Reward 已支付。若 Evaluation 状态无法确定，则会保持为 SUBMITTED/pending，保留有效预留；即使有限重试次数耗尽，也不会消耗奖励资格或因此被视为拒绝。

奖励轮询会观察全部六种公开奖励状态，并将请求总数限制为最多十次 HTTP 交互（包括重试）。如果达到该上限前至少收到一次有效的 pending 或 approved_pending 结果，则最后一个有效的非终态结果仍视为成功，而不会变成超时；调用方之后可以主动刷新。

Alpha 是概念验证：Hondo 会以尽力而为的方式自动发送符合条件的奖励，采用有限次数的自动重试并记录证据。Completion 2xx 仅表示已收到并持久化。不存在付款 SLA、个别调查、手动重新发送、补偿、替代付款途径，也不存在任意授权不予付款的情况。必须披露的渠道包括 TaskGet、Task Definition、OpenAPI/Agent 文档、Taskboard 和 SDK 文档。SDK 会保留此服务器提供的 poc_terms 披露内容；不会将其转化为付款承诺或政策决定。

现有的 OpenClaw worker 端点和 X-Internal-Secret 保持内部使用且不作更改。只读 MCP 无需密钥，也不提供 Task 修改工具。Bazaar 注册和付费 Task Offer 路由不属于此 SDK worker 候选版本的范围；该版本不提供 Task Offer 创建模型、支付封装或注册命令。

定时 HTTP GET 批处理 worker 边界（v1.18.0 候选版本）

v1.18.0 候选版本新增严格的 generic-v2 Task 层，以及用于 scheduled_http_get_batch.v1 的专用适配器。已发布的 v1 Task 继续使用现有客户端、模型、扁平错误信封、路由和重试规则。对于已知的 v2 Task，Claim 只会发送一次。无法确定结果的 Claim 会报告为 CLAIM_OUTCOME_UNKNOWN，且绝不会重放。就绪状态是即时调度时的权威依据；它会向适配器提供与 Claim 绑定的 Manifest 信息，但不会将这些信息转化为公开模型数据。 Claim 令牌和已签名的 Manifest URL 都是机密信息。它们不会出现在常规转储、表示形式、错误、日志、检查结果、MCP 消息、CLI 参数、CLI 输出、Completion 报告和日志载荷中。已签名的查询字节仅保存在私有的插槽式传输状态中；常规 dataclass、vars() 和 pickle 序列化会安全失败，不会泄露这些字节。私有凭据文件编解码器是 Claim 凭据唯一的本地序列化边界。task claim-v2 要求同时提供凭据路径和日志路径，并且仅在 Claim 成功后、写入可用凭据前，创建一次与定义绑定的日志。运行/恢复命令只会加载该日志：如果日志缺失，则绝不会重建，并且不会进行任何就绪状态、Manifest、目标、Completion 或状态 I/O。调用方绝不会将 Claim 令牌或已签名 URL 粘贴到命令行或模型提示词中。仅供检查的 MCP 不需要密钥，也没有 Task 修改或执行工具。

官方适配器会在每次尝试时重新解析 A 和 AAAA 记录，以获取确切的已签名 Manifest URL。IPv6 资格检查采用固定的 IANA 分配和特殊用途快照，并且不依赖运行时网络；若无法确认则安全失败，也不使用 ipaddress.is_global 或有限的拒绝列表。只要有一个答案不符合要求，就会在创建套接字前拒绝整个 DNS 答案集。适配器会固定一个通过验证的数字 IP 对端，检查已连接的对端是否与该固定 IP 完全一致，并保留规范主机名，用于 TLS SNI、证书验证和 Host 标头。它会禁用重定向、环境代理、Cookie、Authorization、代理授权、netrc、环境会话、请求正文、调用方标头和自动内容解码。只接受 identity 编码；已签名的查询会被脱敏，绝不会转发给目标。

Manifest 获取操作会在单个 5 秒时间窗口内最多尝试 3 次。只有在后续尝试还剩下完整的单次尝试预算时，才会启动该次尝试。响应标头和成功的 Manifest 正文分别限制为 32 KiB，而非 200 响应的正文绝不会被读取。策略检查优先于重试分类：例如，503 响应同时带有 Content-Encoding: gzip 时，会被判定为编码失败，且只尝试一次、读取 0 个正文字节。

目标按 Manifest 中的顺序依次运行。每次对目标执行 I/O 前，SDK 都会持久写入 ATTEMPT_STARTED。每个目标最多尝试一次；结果不确定的派发绝不会重发。在 T+5 时，适配器会停止启动新目标，并为其余目标记录类型化的 not_attempted_deadline 结果。目标响应正文和正文摘要不会被存储。

本地日志有版本控制、校验和及锁，并在创世时不可逆地绑定到 Task ID、完整的 Task Definition 元组、单向本地 Claim 句柄和确定性派生的 Execution ID；它还会在 T 时持久绑定就绪 Manifest 摘要。日志使用同目录原子替换，刷新文件以确保状态持久，在原生 Windows 上会在替换前关闭参与替换的对象，并在支持的平台上刷新目录元数据。缺失、损坏、未绑定的旧版、定义不匹配或绑定不明确的状态都会在网络 I/O 前安全失败。恢复过程会保留精确冻结的规范报告字节，并通过终止状态 COMPOUND_COMPLETION_ACKED 区分每个崩溃边界。 Compound Completion 恢复会优先检查 Submission 状态。一个稳定的同级跨进程操作锁会将全新的日志读取、状态/关闭判定、派发预留、POST、歧义恢复和确认持久化纳入一个连续的临界区。只有在先前尝试次数为 0 时，全新的 Completion 才能预留首次 POST；恢复流程则始终先检查状态，即使先前尝试次数为 0 也是如此。只有在已有一次预留、状态确认不存在且尚未关闭时，才可能执行第二次 POST，并且始终复用相同的 Submission ID 和完全相同的冻结字节。已存储的准时回执在关闭后仍可恢复；在关闭时或之后，绝不会新接受不存在的回执。Completion 回执与 Evaluation、奖励审批、结算和付款彼此独立。

日志一旦原子地记录 COMPOUND_COMPLETION_ACKED，派发边界即为终态。此后每次恢复都只使用持久化的非敏感回执绑定信息和不带令牌的 Submission 状态传输；不会调用 Claim 就绪性检查、重新获取 Manifest、执行目标或重新发送 Completion。绑定的状态若包含 terminal=true，便会传回日志；日志会验证所有冻结报告和确认标识，然后将公开安全的状态证据原子地持久化为 TERMINAL_STATUS；非终态或不匹配的状态无法越过该边界。

from ln_church_agent import AgentTaskV2Client

# See examples/scheduled_http_get_batch.py for the complete private-credential
# and durable-journal flow. Do not copy a Claim token or signed Manifest URL
# into application logs, a model prompt, or command-line arguments.
client = AgentTaskV2Client()
tasks = client.list_tasks()

规范测试夹具随附于 ln_church_agent/contracts/v18-scheduled-http-get-batch-contract-v1.json，其 SHA-256 为 51b137a3d27eeb8a8cd69341cbbfd09e38309b3da4adf569e6c0cea2f56a8c14。Wheel 和 sdist 必须包含完全相同的字节，并以最终 LF 结尾。此功能不会新增依赖项。

Linux 候选版本的证据涵盖确定性测试套件、测试夹具一致性、v1 回归、机密扫描、日志崩溃矩阵，以及精确的、由测试夹具驱动的 42 行网络矩阵：21 个必需向量中的每一个，都会针对 SDK 管理的 Manifest 范围和目标范围，分别通过 ControlledHTTPSConnector.fetch 运行，并记录解析器/连接/发送/读取次数。证据还涵盖软件包标识。原生 macOS 和原生 Windows 仍是独立的资格验证阶段，用于验证各自的文件系统锁定与持久性、DNS、套接字对端和 TLS 行为；模拟不能作为原生平台的资格验证。原生 Windows 资格验证会测试替换前先关闭句柄的行为，且不要求 PowerShell 5.1。若 WSL2 的 SDK 运行时为 Linux，则其结果属于 Linux 证据。

这是一个等待独立审计的 Private 源代码候选版本。它不代表已具备发布条件、晋升为 Public、已发布、已部署、已获服务器接受、已获 Evaluation 接受、已获奖励审批或已付款。

显式 MCP 路由与遥测边界

ln-church-agent 提供两个不同的模型上下文协议（MCP）入口：

• 1. 仅检查的 MCP（ln-church-agent-mcp）： 对于企业级、只读或预检检查，请使用 ln-church-agent-mcp。它无需密钥，且绝不会初始化钱包或签名器、付款或执行交易。检查仅接受指向公开 HTTP(S) 目标的 GET 和 HEAD 请求。DNS 响应和每一跳重定向都会根据公网 IP 策略进行检查，并且连接会固定到已验证的地址。环境代理、netrc 和自动重定向均会被忽略。身份编码的响应正文限制为 1 MiB；在读取正文之前会拒绝经过内容编码的响应。 遥测副作用：此 MCP 绝不会自动提交遥测。只有在明确调用 submit_mcp_observation 时，它才可能提交符合架构白名单的观测数据。提交仅限于规范的 LN Church 观测端点，不跟随重定向，不会重试结果不明确的 POST，并且绝不会返回或读取原始响应正文。公开 URL 会简化为其规范来源；由攻击者控制的标量字段会被简化为固定值或有限白名单中的值。

• 2. 可执行操作的 MCP（python -m ln_church_agent.integrations.mcp）： 仅当操作员明确需要一个可使用已配置凭据执行付费操作（例如使用 Lightning 钱包或 EVM 签名器）的 MCP 服务时，才使用 python -m ln_church_agent.integrations.mcp。

付费接口观察器

ln-church-agent 不仅是一个付款执行器，也是一个强大的付费接口观察器。 inspect 命令会枚举所有提供的 settlement_options，以及 selected_settlement_option（如果执行，SDK 将会选择的选项）。它会清晰地区分不同能力：哪些可以观察，哪些原生支持执行（execution_support）。

APP、AP2 和 ACP 等 Agent 商务接口严格视为商务／授权层。它们按仅检查方式处理，也就是说，SDK 会有意避免自动执行，并在未声明明确的结算通道时明确指出缺少的结算参数（missing_information）。

选择加入 LN Church Observatory： ln-church-agent 可以在本地检查付款接口。 LN Church Observatory 是公开观测层，可在此收集并比较经删减的观测数据、执行证据和互操作性跟踪信息，涵盖 HTTP 402 / x402 / L402 / MPP 接口。

SDK 绝不会自动提交观测数据。 向 LN Church 发布数据必须经过明确同意并主动选择加入。

可验证的报告者身份层（v1.12.0+）

自 v1.12.0 起，SDK 支持通过 ensure_reporter_verification() 使用可选的、由客户端管理的 可验证的报告者身份层。

• 密钥控制与报告真实性：此层仅证明报告 Agent 控制着与其 agentId 关联的私钥。它不验证所提交遥测数据在语义上的正确性或真实性。
• 完全非强制：验证完全可选。遥测提交从根本上保持其隐私优先、选择加入的原则。
• 无信任评分：key_control_verified 不是信任评分、认证、推荐或结算证明。
• self_reported 仍是一等选项：对于 self_reported（未经验证）的 Agent，运行时必须保持功能完全一致。未经验证仅表示未明确执行密钥控制验证流程。
• 无自动钩子：ensure_reporter_verification() 绝不会在 execute_detailed() 或 submit_goal_attempt_observation() 等执行方法中自动触发，从而确保对令牌开销进行确定性管理。
• 安全提示：agentId 可以是 64 个字符的十六进制标识符，但它只会被严格视为公开标识符。**绝不可将私钥作为 agentId 提交。**对于 EVM 公钥验证，agentId 必须明确为带 0x 前缀的 40 个字符的公开地址。

托管平台的边界

ln-church-agent 不是托管钱包、支付处理器或云端支付编排服务。

AWS AgentCore Payments 等托管平台可帮助 Agent 在托管的钱包／会话环境中执行支付。ln-church-agent 专注于开放 Web 的买方侧：检查 HTTP 402 和 Agent 商务界面，区分可执行的结算通道与商务／授权层，执行本地策略，验证结果，并跨协议收集证据。

当你需要托管钱包托管、云端支付会话以及由提供商管理的支付执行时，请使用托管平台。

当你需要轻量、本地、跨协议的检查、决策支持、证据收集、沙盒验证，或非 AWS／开放 Web 互操作性时，请使用 ln-church-agent。

安全提交观察结果

请勿使用底层 execute_request() 方法手动向 /api/agent/external/observe 端点 POST 载荷，因为这会绕过架构规范化，并可能触发严格的内部 HATEOAS／跨源防护规则。

• **标准观察结果：**使用 submit_external_observation()。
• **未映射／未知界面：**使用 submit_unmapped_observation()。

from ln_church_agent import LnChurchClient

client = LnChurchClient()

client.submit_unmapped_observation(
    target_url="https://example.com/api/endpoint",
    detection_note="payment_scheme_unmapped",
    rails_detected=["Payment"],
    status_code=402,
)

注意：未映射的观察结果严格视为发现信号。它们会声明 payment_performed=False 和 verification_status="unverified"。默认遥测自动提交脚本会保持保守；提交未映射观察结果需要明确选择加入。

适用场景

• ln-church-agent：面向遭遇 HTTP 402 挑战的 Agent 的买方侧运行时。
• ln-church-server：用于构建面向 Agent 的付费 API 的提供商侧入门框架。
• LN Church Sandbox：用于基准测试、收据、跟踪记录和互操作性证据的公开验证场地。
• 证据跟踪（v1.8.4+）：ln-church-agent 现在可以将赞助访问和沙盒执行元数据捕获为本地证据（SponsoredAccessEvidence / SandboxEvidence）。沙盒证据严格限定于 LN Church 的受控沙盒环境（evidence_scope: "sandbox_internal"），并且有意不自动提交外部观察结果。原始机密会被安全地编辑隐藏。
• 语料库就绪度（v1.8.5+）：SandboxEvidence 可转换为本地 SandboxCorpusCandidate。这不会提交至 ExternalObserve。最终语料库是否接纳仍由服务端决定。
• 目标尝试记忆（v1.10.0+）：捕获朝既定目标迈进的免费、付费和混合步骤，在应用配方之前，作为 Agent 行为的基础数据湖。

与官方协议 SDK 的关系

ln-church-agent 是官方协议 SDK 的补充，而非替代品。

• 简单的纯协议原生结算：使用官方协议 SDK。
• 当 Agent 需要确定性检查、了解策略的决策支持、HATEOAS 恢复、收据验证、证据采集、跨协议比较或可追踪的付费操作尝试时：使用 ln-church-agent。
• 最终支付权限仍由本地掌控。 网络可以提供建议，但 SDK 的本地 PaymentPolicy 明确优先于远程建议。

---

🧠 AI 决策卡

当 AI Agent 需要做的不只是支付一次 API 调用时，请使用 ln-church-agent。

在 Agent 需要以下能力时选择此 SDK：

• 多通道支持：支持 L402、x402 和 MPP 的工作流。
• 策略执行：本地支出限额、会话预算和信任检查。
• 可验证证据：用于审计的收据、证据记录和跟踪信息。
• 安全停止：妥善处理不受支持或不稳定的支付会话。
• 商业表面检查：检测 OKX APP 风格的 Agent 商业元数据，同时仅在存在受支持的 402 通道时才启用执行。
• 目标条件尝试跟踪：明确记录多步骤尝试（免费、付费、混合）及其可选结果。

如果任务只是一次性、低风险的 pay-and-fetch，请使用轻量级 402 代理。

---

⚡ 首次成功：先检查，再支付

先运行无需支付的检查命令。此操作无需配置钱包或私钥，即可验证 API 和端点功能。

pip install ln-church-agent
ln-church-agent inspect https://kari.mayim-mayim.com/api/agent/sandbox/mpp/charge/basic --json

此命令不会执行支付。它会检测 HTTP 402 挑战、识别支付通道、推荐安全操作，并打印下一条命令。

标准的首次流程：inspect → decide → pay → verify → trace

• 有关准确的功能和执行边界，请参阅功能矩阵。
• 有关未来标准跟踪和暂缓事项，请参阅标准观察对齐。

---

🧭 Agent 商务界面检查

ln-church-agent v1.8+ 将 inspect 从支付通道预检工具扩展为 Agent 商务界面检查器，v1.9.0 新增了对 Google AP2 和 ACP 的明确分类。

它可以安全地检测更高阶的商务元数据，首先支持 OKX Agent Payments Protocol (APP)、AP2 授权书和 ACP 结账，同时在检查期间严格禁用结算执行。

在 v1.9.1+ 中，检查结果还可包含 AP2 / ACP / 类似 OKX APP 界面的引导式交接元数据。这些信息会告知上游 Agent 应向网站询问什么、哪些内容不能视为结算证明、需要哪些证据、缺少哪些信息，以及为何可能需要操作员批准。

类似授权信号的检测旁路工具（v1.12+）： inspect 工具还可能将未经验证的激励信号（例如，水龙头、试用额度）检测为本地旁路观察结果。

• 这不保证授权可用。
• 它不验证已签名的授权令牌或其可兑换性。
• 它不会自动提交到 Hon-den 观察网络。
• SDK 严格遵循 not_a_recommendation、not_a_verdict 和 unassessed_is_not_failed 原则。

输出示例：

{
  "ok": true,
  "url": "https://api.example.com/checkout",
  "http_status": 402,
  "surfaces_detected": ["ACP"],
  "settlement_rails_detected": ["x402"],
  "surface_type": "checkout",
  "commerce_protocol": "acp",
  "commerce_intent": "agentic_checkout",
  "settlement_rail": "x402",
  "recommended_action": "observe_only",
  "will_execute_payment": false
}

{
  "handoff_mode": "guided_handoff",
  "approval_required": true,
  "ask_site_for": ["quote_details", "settlement_rail_options", "receipt_or_proof_model"],
  "do_not": ["treat_authorization_artifact_as_settlement_proof"],
  "required_evidence": ["explicit_price", "merchant_identity", "settlement_rail", "receipt_model"]
}

此区分是有意为之：

• L402、MPP 收费和受支持的 EVM x402 形式被视为可执行支付通道。Canonical SVM exact 仅支持检查，并会安全停止；仅其底层载荷构建器仍可用。
• Google AP2 / ACP / OKX APP / 卡网络 Agent 支付被视为商务、授权、身份或结账界面。即使它们提供了具体的、兼容 HTTP 402 的结算路径，其基线建议仍默认为观察。
• inspect 永远不会执行支付、初始化钱包、签署载荷或调用经纪服务。

当你的 Agent 需要了解付费操作界面，并在之后决定是否可以安全执行支付、是否不受支持，或是否仅供观察时，请使用此模式。

---

🔭 付费域名观察名额（v1.14.0+）

ln-church-agent 允许 Agent 或人工操作员通过 HTTP 402 付费操作，明确登记一个公共域名，以提交给 LN Church 天文台队列进行为期 7 天的扩展观察。

严格的架构与安全规则：

• 付费域名观察名额是向 LN Church 付费提出的请求，而不是向目标域名付费。
• 它不是安全扫描、背书、认证、推荐或信任评分。
• MVP v0 不验证域名所有权。（requester_paid=true，domain_owner_verified=false）。请求方已付费与域名所有者已验证是完全独立的概念。
• 从此队列获取目标内容的内部工作进程受严格的 public-safe 约束（仅限 GET/HEAD；不提交表单、不登录、不进行漏洞扫描、不向目标付费）。
• 结果会发布到 public-safe 读取模型。

CLI 用法：

# Register a domain for observation (approx 1 USDC via x402)
ln-church-agent observe-domain register example.com --pay

# Check the active queue status (free, read-only)
ln-church-agent observe-domain status obsreq_xxxxx

# Read the public-safe observation facts (Read Model)
ln-church-agent observe-domain read-model example.com

SDK 用法：

from ln_church_agent import LnChurchClient

client = LnChurchClient(private_key="0x...")

# 1. Paid Registration (Requires funds)
res = client.register_domain_observation_slot("example.com")
print(f"Request ID: {res.request_id}")

# 2. Check Status (Free, Read-Only)
# Can be called safely without private keys: LnChurchClient(agent_id="cli_observer")
status_client = LnChurchClient(agent_id="cli_observer")
status = status_client.get_domain_observation_request(res.request_id)

# 3. Fetch Domain Read Model (Free, Read-Only)
read_model = status_client.get_domain_observation_read_model("example.com")

购买结果与恢复

Monzen 和 Bazaar Surface Comparison Facts 购买、Domain Observation Slot 和 Verified Domain Track 会通过 ExecutionResult.paid_result_metadata 暴露收到的结果标头。此属性会返回副本，其中仅包含收到的 result_handle、request_hash 和 result_expires_at。域名注册响应也会将这些内容作为显式属性公开。结果过期时间与 Slot 或 Track 的产品过期时间是分开的；不会根据业务正文推断缺失的元数据。

请将此元数据保密。常规表示形式、默认序列化结果和公开响应标头都会省略证明值；显式访问 .response 会保留原始业务正文。可选的 Track 证明文件可以包含 result_expires_at；不含此字段的现有文件仍然有效。

# Use the existing request entry point with the original purchase's saved handle.
recovered = client.execute_detailed("GET", f"/api/bazaar/paid-results/{saved_handle}")
original_body = recovered.response

恢复 GET 请求绝不会购买或跟随购买导航，包括遇到意外的 402 响应时。非成功响应会抛出 PaymentExecutionError，其中包含实际的 status_code。已知的 PAID_RESULT_PERSISTENCE_UNCONFIRMED、STATE_UPDATE_FAILED 和 BACKEND_RESPONSE_PARSE_FAILED 响应也会保留 code；它们不会授权新的购买，也不会抹去已知的付款事实。结果缺失或过期并不能证明未付款。

---

🛡️ 已验证域名赞助方（v1.15.0+）

对于付费 Domain Observation Slots，ln-church-agent v1.15.0+ 允许赞助方在 .well-known 路径下放置确定性挑战文档，以通过加密方式证明其控制目标域名的公共网页。

严格的架构与安全规则：

• 仅证明域名控制权： 这只能证明赞助方能够在域名上发布文件，明确不构成法律所有权证明。
• 不构成评判： 已验证域名不会因此获得更高排名、被天然视为可信，也不会获得 LN Church 背书（not_a_verdict: true、not_an_endorsement: true）。
• 不自动执行： SDK 不会在注册后自动发出挑战或验证赞助方，以防止未经提示的执行。
• 防止机密泄露： CLI 和 SDK 会严格从标准输出中隐去证明标头（X-LN-Result-Handle、X-LN-Request-Hash）以及 challenge_token。

CLI 用法：

# 1. Issue a challenge and save the document locally safely
ln-church-agent observe-domain sponsor challenge obsreq_xxxxx \
  --output-file ".well-known/ln-church-domain-sponsor.json"

# 2. (Manual Step) Publish the JSON file to exactly:
# https://{target-domain}/.well-known/ln-church-domain-sponsor.json

# 3. Request the LN Church backend to fetch and verify the document
ln-church-agent observe-domain sponsor verify obsreq_xxxxx

SDK 用法：

from ln_church_agent import LnChurchClient

client = LnChurchClient(agent_id="domain_sponsor_cli")

# 1. Issue Challenge
challenge = client.create_domain_sponsor_challenge(
    request_id="obsreq_xxxxx",
    result_handle="pr_...", 
    request_hash="sha256:..."
)

# 2. Save Document Safely (excluding headers/secrets from the file)
client.save_domain_sponsor_challenge_document(
    challenge, 
    ".well-known/ln-church-domain-sponsor.json"
)

# 3. Verify
verified = client.verify_domain_sponsor(
    request_id="obsreq_xxxxx",
    result_handle="pr_...", 
    request_hash="sha256:..."
)

print(f"Domain Control Verified: {verified.domain_control_verified}")
print(f"Legal Ownership Proof: {not verified.not_legal_ownership_proof}") # Evaluates to False

---

MCP：仅供检查的支付界面发现

ln-church-agent-mcp 是随 ln-church-agent 打包的仅供检查的 MCP 入口点。

它面向兼容 MCP 的 Agent，帮助其发现和检查 HTTP 402 / Agent 商务界面，以便在决定是否使用独立支付执行引擎之前进行评估。

v1.9.2 新增 ln-church-agent-mcp，这是一个无需密钥的 MCP 服务，供需要检查付费界面而不执行支付的 AI 编排框架使用。

它提供检查、解释和观察载荷工具；在可用时返回 Guided Handoff 元数据，并将 payment_performed=false 硬性锁定。

ln-church-agent-mcp 是一个面向安全侦察的公开、仅供检查的 MCP 服务。 它会解析 HTTP 402 付费界面，并对 L402、x402、MPP、OKX APP、AP2 和 ACP 进行详细的结构分类。

• 仅限 GET/HEAD：检查会在访问网络前拒绝所有其他方法，且只接受绝对的公共 HTTP(S) 目标。
• 固定公共网络：字面 IP 和所有 DNS 答案都会根据公共 IP 策略进行检查。每个重定向跳转都会重新验证，并通过已验证的 IP 进行连接，同时保留原始 HTTP Host 和 HTTPS 证书主机名。拒绝从 HTTPS 降级到 HTTP。
• 不使用环境代理或凭据：不会使用环境代理变量、NO_PROXY、netrc、调用方提供的代理、响应 Cookie 或跨跳授权凭据。
• 限制响应大小：请求使用 Accept-Encoding: identity。从原始响应流式读取未编码的正文，并限制为 1 MiB；在读取任何正文前拒绝压缩响应。DNS、连接/TLS、状态/标头、正文和重定向处理共用一个墙钟截止时间。超时和传输故障会返回固定且经过脱敏的诊断信息。
• 不执行支付：只会严格分析响应并建议 recommended_action。不会初始化支付客户端、钱包、签名器、RPC 客户端，也不会进行支付重试或使用凭据。
• 无需私钥：完全不依赖钱包适配器或身份凭据运行。
• 输出经过脱敏：线上请求路径和查询参数可能会发送给被检查的目标，但公开 URL 字段仅保留最初请求 URL 的规范源，并且绝不保留重定向目标、原始路径、查询参数或片段。不会公开原始发票、支付目标、金额、macaroon、preimage、收据令牌、响应正文或原始异常字符串；其他公开标量使用固定值或有限允许列表。
• 仅允许明确提交规范遥测数据：不会自动提交观察数据。显式的 submit_mcp_observation 工具仅接受构建器的规范允许列表架构和规范端点 https://kari.mayim-mayim.com/api/agent/external/mcp-observe，不跟随重定向，最多执行一次 POST，且仅返回状态元数据或固定故障代码。对于结果不明确的超时或网络故障，会返回 observation_delivery_unknown，并安全停止，不会重放请求。

远程 MCP 范围说明：
v1.9.2 提供捆绑的 stdio MCP 服务，用于发现仅供检查的支付界面。
此版本不包含远程 MCP / Claude 自定义连接器托管；该功能计划作为未来范围。

若要向 AI Agent 提供这些安全工具：

ln-church-agent-mcp

---

支付失败观察

v1.9.4 引入了一个结构化层，用于记录和分析 402 支付尝试失败。 该层不会将失败视为二元的“故障”状态，而是将其视为观察记录——在特定条件下遇到阻碍的结构化证据（例如，动态 feePayer 字段导致重试不匹配）。

• 结构化知识：将执行崩溃转换为可复用的 PaymentFailureRecord 记录。
• 隐私保护设计：自动为原始密钥（前像、私钥、macaroon）生成指纹，并从挑战字典和错误消息中将其删去。
• 互操作性分析：检测服务端要求在首次检查和支付重试之间是否发生变化。

代码示例

from ln_church_agent.failures import build_payment_failure_record, build_payment_failure_observation_payload

# 1. Build a local record of the failure
record = build_payment_failure_record(
    endpoint="https://api.example.com/data",
    rail="x402",
    scheme="exact",
    failure_subclass="no_matching_payment_requirements",
    server_message="Your macaroon is invalid", # 'macaroon' will be [REDACTED]
    challenge_before={"accepts": [{"feePayer": "NodeA"}]},
    challenge_after={"accepts": [{"feePayer": "NodeB"}]},
    secondary_client_used="x402-official-client"
)

print(record.changed_fields) 
# Output: ['accepts[0].feePayer']

# 2. Build a public-safe payload for future ingestion
payload = build_payment_failure_observation_payload(record, agent_id="agent-007")
print(payload["evidence"]["payment_performed"]) 
# Output: False

注意：SDK 目前会在本地构建这些记录。本版本暂不支持服务端，因此禁用了自动提交到 LN Church 失败注册表的功能。

---

Surface 预检读取模型（v1.11.0+）

在访问特定付费接口之前，Agent 可以明确读取 Hon-den 对该端点的历史观察记录，以检查过去遇到的阻碍、证据等级和结算选项。

• 这不是建议，而是一条可复用的观察记录。
• 这不是判定，而是一条可复用的观察记录。
• 这不是支付证明。
• 它不会执行支付。
• 最终决策权仍由你的本地运行时（PaymentPolicy / TrustEvaluator）掌握。
• 未知接口并非“不安全”——这只表示注册表尚未观察过它们。

from ln_church_agent import LnChurchClient

client = LnChurchClient(base_url="https://kari.mayim-mayim.com")

# Query deterministically by URL and protocol shapes
card = client.get_surface_preflight(
    target_url="https://api.example.com/protected",
    method="GET",
    rail="x402",
    network="eip155:8453",
    asset="USDC",
    authorization_scheme="x402",
    draft_shape="exact",
)

print(card["schema_version"])
print(card["surface"]["known"])
print(card["not_a_recommendation"])
print(card["guardrails"]["final_authority"])

# Or query directly by Surface Key if known
card2 = client.get_surface_preflight(surface_key="surface_0123456789abcdef01234567")

---

目标尝试观察（v1.10.0）

ln-church-agent 现在可以明确提交 Day 1 目标尝试观察记录。

目标尝试记录 Agent 为声明的目标尝试了什么、使用了哪些接口、这些步骤是免费、付费、混合、仅观察还是模拟执行，并可选择记录该尝试是否实现了目标。

这不是自动遥测。

它不会：

• 执行支付，
• 推荐方案，
• 从 execute_detailed() 自动提交，
• 改变 L402/x402/MPP 的执行行为。

如果省略 outcome，该尝试会被记录为 unassessed。这是有意为之：当目标尝试图谱采用更新的目标分类体系和结果评估标准重新解读时，未评估的尝试仍可能发挥作用。

client.submit_goal_attempt_observation(
    goal={
        "goal_text": "Explain this Solana transaction and identify missing confidence signals",
        "declared_goal_type": "tx_investigation",
        "domain_hint": "crypto"
    },
    attempt={
        "attempt_mode": "free",
        "completion_status": "partial_success",
        "total_monetary_cost": 0,
        "total_reasoning_cost_estimate": "medium"
    },
    steps=[
        {
            "step_index": 1,
            "step_role": "fetch",
            "surface_key": "web:solscan:tx_page",
            "surface_type": "web_page",
            "payment_performed": False,
            "status": "success",
            "output_semantic_type": "tx_summary"
        }
    ],
    evidence={
        "evidence_class": "agent_report",
        "verification_status": "self_reported",
        "payment_performed": False
    }
)

🧭 目标尝试记忆读取模型（v1.10.0）

虽然完整的行为映射可通过高级图谱实现，但在主动推理循环中分析完整的 monzen-graph.json 可能导致上下文窗口膨胀。ln-church-agent v1.10.0 引入了两个轻量级的静态 S3 快照端点，以便高效读取历史尝试上下文。

自主 Agent 的合理读取顺序

为尽可能减少数据摄取和分配开销，自主 Agent SHOULD 按以下层级查询信息：

1. **目标尝试摘要（免费）：**查询总体数量计数器和未评估比例，以判断基础层的可行性。
2. **目标接口候选项（付费——1 SAT）：**获取网络过去为特定目标使用过的最多 20 个历史观察接口。
3. **完整共振图谱（高级——10 SATS）：**仅在需要进行深入分析性的结构映射时，下载完整的多链数据集。

get_goal_attempt_summary() 及其异步版本使用非购买型 GET。如果收到意外的 402 响应或其他非成功响应，则会抛出 PaymentExecutionError，其中包含实际 HTTP 状态；不会发生支付、预算恢复、探测或自动导航。明确选择的付费候选项仍会沿用其购买流程。

代码示例：获取摘要和候选项

from ln_church_agent import LnChurchClient, AssetType

client = LnChurchClient(private_key="0x...")

# 1. Fetch Lightweight Summary (Completely Free)
summary = client.get_goal_attempt_summary(
    goal_type="tx_investigation",
    domain_hint="crypto"
)
print(f"Total Attempts Recorded: {summary['goals'][0]['attempt_count']}")

# 2. Fetch Observed Candidate Surfaces (Paid: 1 SAT / 0.001 USDC / 1 JPYC)
# Warning: If unpaid, this triggers a standard HTTP 402 challenge loop.
candidates = client.get_goal_surface_candidates(
    goal_type="tx_investigation",
    domain_hint="crypto",
    prefer_free_first=True,
    asset=AssetType.SATS,
    scheme="L402"
)

# Candidates are observed records, NOT recommendations or verdicts
for surface in candidates["candidate_groups"][0]["candidate_surfaces"]:
    print(f"Observed Surface: {surface['surface_key']} (Used: {surface['used_count']} times)")

严格的架构约束：

• 不是推荐，而是可复用的观察记录： 候选面是历史记忆标记，不是配方预测或当前判定（not_a_recommendation: true）。
• 完整性尚未评估： 缺少结果的追踪记录表示尚未评估状态，绝不表示执行错误。
• 固定成本隔离： 候选项查询使用独立的定价表，与完整图谱定价完全解耦。

---

⚡ 5 分钟快速上手

根据当前目标选择执行路径：

路径 A：通用付费获取（开放 Web 集成）

与开放 Web 上任何兼容 HTTP 402 的 API 集成。SDK 会自动处理标准付款协商循环，让 Agent 无需处理加密方面的复杂性。

from ln_church_agent import Payment402Client

client = Payment402Client(base_url="https://your-402-api.com", private_key="0x...")

# Inspects 402 -> Applies policy -> Pays if allowed -> Retries -> Verifies response
result = client.execute_request(
    method="POST",
    endpoint_path="/api/protected",
    payload={"input": "data"}
)
print(result)

路径 B：Agent 工具集成（MCP）

让任何兼容 Model Context Protocol（MCP）的 Agent（例如 Claude Desktop）立即具备跨链 402 付款和侦察能力。

export AGENT_PRIVATE_KEY="your-0x-prefixed-key"
python -m ln_church_agent.integrations.mcp

你的 Agent 现在可以直接在推理循环中自主调用付费工具并对工作流进行基准测试。

路径 C：针对 LN Church 沙盒进行公开基准测试

在物理隔离的 Agentic Payment Sandbox 中验证 Agent 的解析和执行能力。这会验证协议合规性（L402 或 MPP），并向 Interop Matrix 报告遥测数据。

from ln_church_agent import LnChurchClient

client = LnChurchClient(private_key="0x...")

# Autonomously validate standard L402 compliance
l402_result = client.run_l402_sandbox_harness()

# Or, validate the new Machine Payments Protocol (MPP) charge flow
mpp_result = client.run_mpp_charge_sandbox_harness()

print(f"L402 Hash Matched: {l402_result.canonical_hash_matched}")
print(f"MPP Hash Matched: {mpp_result.canonical_hash_matched}")

观察 → 语料库 → 合成回放 → Agent 空运行验证

ln-church-agent v1.8+ 补全了 LN Church 互操作循环中的 Agent 端。

它可以读取服务端的 synthetic_from_corpus_v1 回放描述符，并验证本地解析器和决策引擎是否选择预期行为：

• pay_and_verify
• observe_only
• stop_safely
• reject_invalid

这是一个空运行验证路径。它不会执行真实付款，也不会尝试原始线级回放。

from ln_church_agent import LnChurchClient

client = LnChurchClient(private_key="0x...")

# Dry-run a synthetic replay descriptor from the Corpus
replay_result = client.run_corpus_replay(
    corpus_id="corp_12345",
    dry_run=True
)

print(f"Success: {replay_result.ok}")
print(f"Expected: {replay_result.expected_action}, Observed: {replay_result.observed_action}")

---

🛡️ 团队为何采用此运行时

• 避免追踪协议变更： 开发者无需手动追踪每次上游修订。SDK 将 x402 Foundation、IETF（Payment / MPP）和 L402 不断演进的草案抽象为一个 execute_detailed 循环。
• 将最终执行权限留在本地： 通过 Advisor & Final Judge 架构，网络可以提供交易对手风险建议，但执行或阻止付款的最终权限严格保留在本地运行时（PaymentPolicy、TrustEvaluator）。
• 获取可验证的收据： 每次成功结算都会生成结构化、可验证的凭据（SettlementReceipt、PaymentEvidenceRecord），供大模型用于审计自身预算。
• 支持冷启动执行： 原生支持 faucet 和 grant 令牌，仅将其用作入门覆盖项，让零余额 Agent 在进行直接 402 结算前即可引导并启用相关能力。
• 对真实行为进行基准测试： 在将真实流动性投入未知端点之前，先在实时、无状态的公共沙盒中测试 Agent 的逻辑。

---

🔌 协议覆盖范围

SDK 通过统一接口支持多种结算通道。

标准 x402 v2（全球标准）：

• EVM exact（x402）：基于标准 EVM 的结算，使用严格的 EIP-712/EIP-3009 免 gas 授权载荷。

• SVM exact（Solana，仅支持检查和载荷构建）：高层规范同步/异步自动支付通道会在签名者、RPC 或付费重试之前故意快速失败，因为无法证明近期区块哈希的有效期会在规范 Unix expires_at 时刻或之前结束。底层构建器可以构建并验证标准 x402 SVM exact 载荷，但不会广播付款，也不会执行受保护的操作。

• 注意：当前 LN Church exact 沙盒充当结算后验证器。它们要求提交交易哈希/签名证据，并会拒绝未广播的载荷。真正的 V2 exact 结算（由 facilitator 广播）是未来阶段的工作。

• L402 / MPP：标准 Lightning Network 结算（SATS），支持解析 Macaroon 和 BOLT11 发票。

兼容性与沙盒通道（LN Church 扩展）：

• lnc-solana-transfer：通过 Solana RPC 直接转账 SPL Token（USDC）的旧版兼容通道。
• lnc-evm-relay：经过优化的免 gas 中继器编排。
• grant / faucet：冷启动覆盖和赞助访问。
• 像 x402-direct 这样的旧版别名会在内部透明地规范化。

可观测的商业/授权界面（仅供检查）：

• AP2（Agent Payments Protocol）：通过支付/结账授权元数据检测。归类为授权界面。SDK 不会为授权签名。
• ACP（Agentic Commerce Protocol）：通过结账、购物车或委托支付令牌元数据检测。SDK 不会执行 ACP 结账。
• OKX APP：存在显式 APP 元数据或经纪对象时进行检测。
• 银行卡网络/钱包中介的 Agent 支付：视为可观测的商业或授权模式，而非 SDK 原生执行目标。

---

🚀 双栈配置：EVM 执行与 SVM 检查工具

对于同时运行于 Ethereum 和 Solana 生态的 Agent，SDK 会严格隔离 EVM 执行密钥与可选的底层 SVM 载荷构建器。提供 SVM 密钥不会启用高层规范 SVM 自动支付。

from ln_church_agent import Payment402Client, PaymentPolicy
import os

client = Payment402Client(
    private_key=os.getenv("EVM_PRIVATE_KEY"),        # For standard x402 EVM
    svm_private_key=os.getenv("SVM_PRIVATE_KEY"),    # Low-level SVM payload builder only
    svm_rpc_url=os.getenv("SOLANA_RPC_URL", "https://api.devnet.solana.com"),
    policy=PaymentPolicy(...)
)

⚠️ SVM 精确架构与限制：

• 高层规范 SVM 精确自动支付始终会在签名者、RPC 或付费重试之前停止。Solana 最近区块哈希的有效性以区块高度表示，无法通过机械方式限定为不晚于规范的 Unix expires_at。

• svm_private_key 仅供底层载荷构建器使用，且必须是标准的 64 字节 Base58 编码 Solana 密钥。这不会让高层通道变为可执行。

• 底层 SVM 精确构建器不同于旧版 lnc-solana-transfer 路由，接受使用 network: "solana:<genesisHash>" 的 scheme: "exact" 输入。

• 线级精度： 交易构建器会保留并使用原始 PaymentRequirements.asset（SPL Token Mint Address）和原始 amount（最小单位）来构建线级交易。可读性规范化仅在内部用于策略和预算评估。

• ATA 限制： 目标关联代币账户（ATA）必须已存在。目前的 SDK 交易构建器不会注入 ATA 创建指令。

• 支持的 Mint： 内部构建器目前仅支持已知的 USDC Mint。未知 Mint 因小数位数未知而会被拒绝。

• 指令约定： 构建器会按顺序生成 CU limit → CU price → TransferChecked → exactly one Memo。

• Memo 约定： 未提供 extra.memo 时，Memo 为 16 个随机字节，以 32 个小写十六进制字符编码。提供 extra.memo 时，使用传入的 UTF-8 值。超过 256 个 UTF-8 字节的值会被拒绝。

• 架构说明： 本地 SVM 精确交易构建器仅构建并在本地验证标准化的 VersionedTransaction 载荷；它不声称能够执行高层规范支付。

• 互操作验证： x402 Python 2.16.0 facilitator 验证器接受未提供和已提供 extra.memo 的载荷。

---

🎟️ LN Church 的两种入门路径（冷启动覆盖）

虽然直接结算（x402/L402/MPP）仍是标准付费路径，但 LN Church 提供两种用于冷启动执行和沙盒测试的入门路径。两者都会作为 paymentOverride，在标准结算之前执行。

1. 零余额水龙头回退

为没有可用加密货币的 Agent 提供的一次性回退方案。严格用于初始能力验证。

from ln_church_agent import LnChurchClient, AssetType

client = LnChurchClient(
    private_key="0x...",  # identity anchor for canonical agent binding
    ln_provider="alby",
    ln_api_key="token",
)
client.init_probe()
client.claim_faucet_if_empty()

result = client.draw_omikuji(asset=AssetType.SATS) # Uses Faucet override

2. 赞助授权访问

使用受信任赞助方签发的签名、限定范围且仅可使用一次的授权令牌执行。这为 A2A 环境中的赞助方出资预付款分发提供了实验性基础。

ln-church-agent v1.8.3 可在使用前对授权令牌进行本地诊断（client.explain_grant()），说明该令牌对于目标路由／方法／受众／agentId 是否看起来可用。此诊断仅供参考；LN Church 后端仍是权威验证方，并会强制执行单次使用限制。

from ln_church_agent import LnChurchClient

client = LnChurchClient(
    private_key="0x...",  # identity anchor for canonical agent binding
    base_url="https://kari.mayim-mayim.com",
)
client.init_probe()

client.set_grant_token("<JWS_GRANT_TOKEN>")
result = client.draw_omikuji()  # Uses Grant override

---

📜 标准跟踪政策

此 SDK 旨在遵循围绕 HTTP 402 Agent 付款不断演进的开放标准，确保应用开发者无需逐一跟踪各项协议。

• 规范性上游参考： Coinbase x402、IETF draft-ryan-httpauth-payment-01（MPP）以及 Lightning Labs L402。
• 跟踪政策： 此 SDK 优先采用各协议当前的标准路径。旧版和特定生态系统的流程仍可作为回退兼容路径使用。
• 设计目标： 一个 SDK，一个执行循环，多种 402 付款通道。

随着上游标准不断演进，此 SDK 致力于在稳定的开发者接口之下吸收这些变化。如果你使用此 SDK，就无需手动跟踪 402 生态系统中的每次协议修订。

关于不断演进的 MPP 标准的说明： ln-church-agent 并不试图取代官方 MPP SDK。相反，它专注于买方侧的运行时问题：策略检查、挑战解析、付款形式遥测、证据采集，以及对 L402、x402 和新兴 MPP 风格 Payment 挑战的互操作性观察。例如，目前正在积极观察和分类 MPP 会话意图以用于遥测，但尚未将其作为完整的运行时流程执行。

---

⚖️ 顾问与最终裁决者架构

Agent 可以将 Monzen 网络作为证据丰富的顾问，在付款前评估交易对手风险，并在执行后验证语义结果。

关键在于，网络可以提供建议，但最终决定权仍在本地运行时。 LN Church 后端会返回结构化建议（例如，Sanctification 状态、历史不匹配情况），但 SDK 的本地 PaymentPolicy 和 allowed_hosts 配置始终会明确优先于远程建议。

---

📡 已验证域名轨道精简工作流

通过 CLI 为域名注册公共安全观察轨道，并建立赞助证明。

# 1. Register and pay (19 USDC)
ln-church-agent observe-domain track register kari.mayim-mayim.com \
  --pay \
  --max-spend-usd 25 \
  --proof-file .ln-church/vdt-kari-proof.json

# 2. Generate sponsor challenge file
ln-church-agent observe-domain sponsor challenge obsreq_123 \
  --proof-file .ln-church/vdt-kari-proof.json \
  --output-file .well-known/ln-church-domain-sponsor.json

# (Host the generated file at your domain's /.well-known/ path)

# 3. Verify sponsorship
ln-church-agent observe-domain sponsor verify obsreq_123 \
  --proof-file .ln-church/vdt-kari-proof.json

# 4. Check status
ln-church-agent observe-domain track status obsreq_123

确认证明文件在本地存在。

此文件包含 result_handle/request_hash 材料。

请勿发布。请勿提交。

test -f .ln-church/vdt-kari-proof.json

发布后，确认公共挑战文档可访问。

curl -I https://kari.mayim-mayim.com/.well-known/ln-church-domain-sponsor.json

确认已验证轨道的状态。

ln-church-agent observe-domain track domain kari.mayim-mayim.com

Test-Path ".ln-church/vdt-kari-proof.json"

curl.exe -I "https://kari.mayim-mayim.com/.well-known/ln-church-domain-sponsor.json"

ln-church-agent observe-domain track domain kari.mayim-mayim.com

---

📚 更多文档

• 快速入门与身份验证
• 架构与功能
• LN Church 朝圣之旅
• 集成（MCP 与 LangChain）
• Monzen 观察网络

付费服务试用（v1.18.7）

原生 Python PaidServiceTrialTaskClient() 会选择 paid_service_trial.v2 / Definition 2.0.0。如需显式使用 v1 进行发现和 Claims，请使用 PaidServiceTrialTaskClient(version="v1")。已保存的 Claims 和日志恢复始终保留其原始版本。请使用 PaidServiceTrialExecutor，并显式配置 signer、 PaymentPolicy 和持久化的 PaidServiceTrialJournal。signer 必须控制 Claim 奖励地址。消费前必须先成功 Claim。v1.18.6 会持久保留原始 Claim 请求，以便调用 recover_claim(task_id, idempotency_key=...)； 客户端和执行器日志在重启后必须使用同一个 claim_directory。 无关的 Bazaar 元数据不再会阻止有效购买。 v1.18.7 会在标准 HTTP 中保留 Payment-Required 和 Payment-Response，并公开安全的 API 错误详情。恢复 Claim 需要原始 Task/key、 版本和私有目录，不需要 Execution ID、凭据或令牌。

worker 会购买一个固定的 Base/native-USDC x402-v2 exact EIP-3009 请求（1–10,000 个 USDC 最小单位）。V2 使用 Task 的不可变 GET 或 POST 请求；v1 仍使用 GET。 POST 会发送精确的规范 JSON UTF-8 字节，这些是公开的 Task 输入。未付款条款检查使用相同的方法、查询和请求正文，可能对目标端产生副作用。不会自动探测其他方法。它会在分发前保存购买身份，即使 HTTP 失败或未返回交易哈希，也会报告该身份。恢复操作绝不会自动再次购买。报告已被接受、购买已验证、20,000 个最小单位的奖励已获批准、款项已确认，这些是彼此独立的事实。收入和交付均不作保证。

请参阅原生 Python 快速入门、 Agent 指南（SKILL.md） 和请求方指南。 显式使用 v1 时，仍使用其 Agent 指南（SKILL.md） 和请求方指南。 不可变且由 Backend 管理的 Definition、Wire、指南、语义 fixture 和 manifest 使用单独的 ln_church_agent/contracts/v185-paid-service-trial-v2/ 镜像。原始 v1 套件在 ln_church_agent/contracts/v185-paid-service-trial/ 中保持不变。每个版本都需要其 完整的固定 Backend 套件。 loader 会在使用前验证其实际字节和 descriptor 摘要； 如果套件不可用，则无法启动新的付费执行。

export_purchase_import_descriptor 会为现有购买导出非机密请求，其中包含显式验证过的 v2 请求、摘要和所选条款。 如需使用原始导入格式，请搭配 endpoint 使用 version="v1"。导出不会发起网络请求或进行新购买。导入会验证支付是否匹配；但无法证明历史方法／请求正文曾被执行，也无法证明产品交付有用。请在导入前保留 descriptor 及其 UUID，并在重试时重复使用。LN 未知的源 SDK 购买必须导入；它并非已经存在的 LN 样例操作。样例付款方和 LN 注册费付款方可以不同。固定方案会用 1/10/100 USDC 分别购买 40/400/4,000 个奖励额度，不退还未使用的额度。外部购买成本与 LN 注册费相互独立。经批准的 Agent 购买／奖励交易链接可以公开；签名、Claim 令牌以及样例／费用证据均为私有。

现有 worker API、默认发现、通用 Payment402Client 重试机制和仅供检查的 MCP 均保持不变。此功能不会添加付费 CLI/MCP 工具。

许可证

MIT