`OasyceClient` 负责把协议读写压成一套适合 Python 程序直接调用的母语接口。 `OasyceClient` compresses protocol reads and writes into a native language for Python programs.
// READ + WRITE + SIGN + EXPOSE
INTERFACE REFERENCE
接口地图 Interface Map
我不想把这页做成一张又长又平的 API 列表。它应该说明一件更重要的事：这个 SDK 不是包装链端点，而是在为 agent 提供不同层次的进入表面。你可以读链、构建交易、原生签名、通过 MCP 暴露给桌面助手，或者接进 LangChain / AHRP 工作流。 I did not want this page to be a long flat API list. It should prove something more important: this SDK is not just wrapping endpoints, it is providing multiple entry surfaces for agents. You can read the chain, build transactions, sign natively, expose the system through MCP, or plug it into LangChain and AHRP workflows.
// ORACLE 真正好的接口层，会让不同形态的 agent 觉得这是它们自己的母语。 A strong interface layer makes different kinds of agents feel that the protocol already speaks their native language.
`Wallet` + `NativeSigner` 让签名不再依赖外部二进制，agent 可以在纯 Python 环境里完成交易闭环。 `Wallet` + `NativeSigner` remove the external binary dependency so agents can complete transaction loops in pure Python.
MCP server 把协议直接暴露给桌面助手，让“查余额 / 注册能力 / 买份额”变成对话里的动作。 The MCP server exposes the protocol directly to desktop assistants so “check balance / register capability / buy shares” become conversational actions.
LangChain tools 和兼容桥把它从单脚本工具推进到可编排、可迁移的 agent workflow 表面。 LangChain tools and the compatibility bridge push it beyond single-script utility into an orchestratable, migratable agent workflow surface.
安装表面 INSTALL SURFACES
oasyce-sdk 核心 SDK：35 个读接口 + 28 个交易构建器 Core SDK: 35 read methods + 28 transaction builders
oasyce-sdk[mcp] 附加 MCP Server：11 个读工具 + 14 个写工具 Adds MCP Server: 11 read tools + 14 write tools
oasyce-sdk[langchain] 附加 LangChain：8 个可直接挂载的 tools Adds LangChain: 8 ready-to-mount tools
oasyce-sdk[all] 完整表面：SDK + MCP + LangChain + signer stack Full surface: SDK + MCP + LangChain + signer stack
from oasyce_sdk import OasyceClient from oasyce_sdk.crypto import Wallet, NativeSigner client = OasyceClient("http://47.93.32.88:1317") wallet = Wallet.create() signer = NativeSigner(wallet, client, chain_id="oasyce-testnet-1") caps = client.list_capabilities(tag="llm") result = signer.register_capability("Translation API", "https://api.example.com", 500000)
接口表面 INTERFACE SURFACES
读写骨架 Read / Write Spine
`OasyceClient` 是最底层的协议接口，负责 REST 查询、交易构建、广播和单位转换。它让 Python 成为协议的一等入口。 `OasyceClient` is the protocol’s lowest-level interface, handling REST reads, transaction building, broadcasting, and unit helpers. It makes Python a first-class entrypoint.
原生签名层 Native Signing Layer
v0.5 的 `Wallet` + `NativeSigner` 把 BIP39、BIP32、bech32、protobuf 编码和 secp256k1 压进纯 Python 栈，摆脱 Go 二进制依赖。 v0.5 brings `Wallet` + `NativeSigner`: a pure Python stack for BIP39, BIP32, bech32, protobuf encoding, and secp256k1, removing Go binary dependence.
AI 助手表面 AI Assistant Surface
MCP server 把浏览市场、查余额、注册能力、买卖份额这些动作直接暴露给 Claude Desktop、Cursor、Windsurf 一类客户端。 The MCP server exposes browsing the market, checking balances, registering capabilities, and trading shares directly to clients like Claude Desktop, Cursor, and Windsurf.
工作流表面 Workflow Surface
8 个 LangChain tools 让 Oasyce 不停在脚本层，而是能直接进入 `create_react_agent` 一类 agent orchestration 流程。 Eight LangChain tools let Oasyce move beyond scripts and plug directly into orchestration flows like `create_react_agent`.
兼容桥 Compatibility Bridge
`SigningBridge` 和 `AhrpChainAdapter` 负责兼容旧链路、CLI 资产和多 agent 执行器，让系统迁移不需要推倒重来。 `SigningBridge` and `AhrpChainAdapter` keep legacy flows, CLI assets, and multi-agent executors compatible so migration does not require a rewrite.
读取面 READ SURFACE
35 个真正计入链端点覆盖的读取方法。`health`、`broadcast_tx`、单位转换属于 helper，不计入这里。 These 35 methods count toward chain endpoint coverage. `health`, `broadcast_tx`, and unit converters are helpers and sit outside this number.
x/capability
AI 服务市场的读取接口：列表、详情、收益、调用记录和模块参数。 Read surface for the AI service market: listing, detail, earnings, invocation history, and module params.
list_capabilities(tag=None, provider=None) list[Capability] get_capability(capability_id) Capability get_earnings(provider) Earnings get_invocation(invocation_id) Invocation get_capability_params() dict x/datarights
数据产权、份额、访问级别、争议和迁移的完整读取面。 Full read surface for data property, share state, access levels, disputes, and migration paths.
list_assets(tag=None, owner=None) list[DataAsset] get_asset(asset_id) DataAsset get_shares(asset_id) list[ShareHolder] get_bonding_curve(asset_id) BondingCurve get_access_level(asset_id, address) AccessLevel get_dispute(dispute_id) Dispute list_disputes(asset_id=None) list[Dispute] get_migration_path(source_id, target_id) MigrationPath get_asset_children(asset_id) list[DataAsset] get_datarights_params() dict x/settlement
托管和清算：单笔托管、托管列表、模块参数。 Escrow and clearing: single escrow, escrow listing, and module params.
get_escrow(escrow_id) Escrow list_escrows(creator) list[Escrow] get_settlement_params() dict x/reputation
链上信誉的查询接口：个人评分、排行榜和参数。 Read surface for on-chain trust: individual reputation, leaderboard, and params.
get_reputation(address) Reputation get_leaderboard() list[Reputation] get_reputation_params() dict x/work
有用工作证明和执行者系统的读取接口。 Read surface for proof-of-useful-work and executor state.
get_task(task_id) Task list_tasks(status=None) list[Task] list_executors() list[Executor] get_executor(address) Executor list_tasks_by_creator(creator) list[Task] list_tasks_by_executor(executor) list[Task] get_work_params() dict get_epoch_stats(epoch) EpochStats x/onboarding
注册状态、债务状态和准入参数。 Registration status, debt state, and onboarding params.
get_registration(address) Registration get_debt(address) Debt get_onboarding_params() dict core
基础链状态接口：余额、账户和最新区块。 Base chain state reads: balance, account, and latest block.
get_balance(address) Balance get_account(address) Account get_latest_block() Block HELPERS OUTSIDE THE 35
broadcast_tx(signed_tx)health()oas_to_uoas(oas)uoas_to_oas(uoas) 写入面 WRITE SURFACE
`OasyceClient.build_*` 负责构建 28 个未签名交易体；`NativeSigner` 在其上提供 15 个 encode -> sign -> broadcast 的便捷动作。 `OasyceClient.build_*` constructs 28 unsigned transaction bodies; `NativeSigner` layers 15 convenience actions for encode -> sign -> broadcast.
x/capability
7 BUILDERSbuild_register_capabilitybuild_invoke_capabilitybuild_update_service_urlbuild_complete_invocationbuild_fail_invocationbuild_claim_invocationbuild_dispute_invocation x/datarights
8 BUILDERSbuild_register_assetbuild_buy_sharesbuild_sell_sharesbuild_file_disputebuild_initiate_shutdownbuild_claim_settlementbuild_create_migrationbuild_migrate x/settlement
3 BUILDERSbuild_create_escrowbuild_release_escrowbuild_refund_escrow x/reputation
2 BUILDERSbuild_submit_feedbackbuild_report_misbehavior x/work
6 BUILDERSbuild_register_executorbuild_update_executorbuild_submit_taskbuild_commit_resultbuild_reveal_resultbuild_dispute_result x/onboarding
2 BUILDERSbuild_self_registerbuild_repay_debt 类型系统 TYPE SYSTEM
22 个 typed models 里，21 个位于 `oasyce_sdk.types`，另 1 个是 signer 专用的 `crypto.TxResult`。 Of the 22 typed models, 21 live in `oasyce_sdk.types`; the remaining one is the signer-specific `crypto.TxResult`.
CapabilityEarningsInvocation
DataAssetShareHolderBondingCurveAccessLevelDisputeMigrationPath
EscrowTxResult
ReputationTaskExecutorEpochStats
RegistrationDebtPowResult
BalanceAccountBlock
crypto.TxResult
@dataclass(frozen=True) class Invocation: invocation_id: str capability_id: str status: str challenge_deadline: str usage_report: dict output_hash: str
设计拆解 DESIGN BREAKDOWN
这页不再把 SDK 当成“Python 包介绍”，而是把它作为 agent 接入经济系统的多表面接口来讲。 This page no longer treats the SDK as a Python package intro, but as a multi-surface interface through which agents enter the economy.
读、写、签名、MCP、LangChain、Bridge 被拆成不同层，是为了让不同角色快速找到自己的入口。 Reads, writes, signing, MCP, LangChain, and the bridge are separated so different operators can find their entrypoint fast.
我保留“参考页”的实用密度，但用 surfaces / groups / chips 组织信息，让它比 API dump 更有导航性。 I keep the practical density of a reference page, but organize it with surfaces, groups, and chips so it navigates better than an API dump.
仍然是冷、准、灰度的控制台语法，靠边框和节奏建立层级，不靠装饰色和玻璃效果。 The page stays cold, precise, and achromatic, building hierarchy through borders and rhythm rather than accent color or glass effects.
hero 的 decode 负责“系统上线”的唯一动势，其余保持静态文档般的信心。 The hero decode supplies the only sense of system boot; the rest keeps the confidence of a static technical document.