oasyce-sdk

Oasyce L1 链 Python SDK —— AI Agent 原生经济系统：产权确权、智能合约、自动仲裁。

安装

pip install oasyce-sdk            # 基础 SDK
pip install oasyce-sdk[mcp]       # + MCP Server（Claude/Cursor/Windsurf）
pip install oasyce-sdk[langchain] # + LangChain Tools
pip install oasyce-sdk[all]       # 全部

MCP Server

让你的 AI 助手（Claude Desktop / Cursor / Windsurf）直接操作 Oasyce 链。

配置 claude_desktop_config.json：

{
  "mcpServers": {
    "oasyce": {
      "command": "oasyce-mcp",
      "env": {
        "OASYCE_NODE": "http://47.93.32.88:1317",
        "OASYCE_FAUCET": "http://47.93.32.88:8080"
      }
    }
  }
}

提供 10 个工具：健康检查、领水龙头、查余额、查 agent 档案、浏览市场、列出能力、查信誉、查数据资产、查开放任务、提 issue。

LangChain Tools

from oasyce_sdk.langchain_tools import oasyce_tools
from langchain.agents import create_react_agent

agent = create_react_agent(llm, oasyce_tools)
agent.invoke({"input": "浏览 Oasyce 市场上有什么 AI 服务"})

快速开始（SDK）

from oasyce_sdk import OasyceClient

client = OasyceClient("http://47.93.32.88:1317")
caps = client.list_capabilities(tag="llm")
bal = client.get_balance("oasyce1abc...")
print(f"发现 {len(caps)} 个能力, 余额: {bal.amount_oas} OAS")

API 参考

构造函数

OasyceClient(base_url="http://localhost:1317", timeout=10)

连接 Oasyce 链节点的 REST API (gRPC-gateway)。

能力市场 (Capability Marketplace)

`list_capabilities(tag=None, provider=None) -> list[Capability]`

列出所有已注册的 AI 能力。支持按标签或提供者地址过滤。

all_caps = client.list_capabilities()
llm_caps = client.list_capabilities(tag="llm")
my_caps = client.list_capabilities(provider="oasyce1abc...")

`get_capability(capability_id) -> Capability`

按 ID 查询单个能力。

cap = client.get_capability("cap-001")
print(cap.name, cap.price_per_call, "uoas/次")

`get_earnings(provider) -> Earnings`

查询提供者在所有能力上的累计收入。

earnings = client.get_earnings("oasyce1abc...")
print(f"累计收入 {client.uoas_to_oas(earnings.total_earned_uoas)} OAS, 共 {earnings.total_calls} 次调用")

`get_invocation(invocation_id) -> Invocation`

查询单个调用记录（含状态、挑战窗口、使用报告）。

inv = client.get_invocation("INV_0000000000000001")
print(inv.status, inv.output_hash, inv.usage_report)

`get_capability_params() -> dict`

查询能力模块参数。

数据资产 (Data Assets)

`list_assets(tag=None, owner=None) -> list[DataAsset]`

列出数据资产，支持按标签或所有者过滤。

assets = client.list_assets(tag="ml")

`get_asset(asset_id) -> DataAsset`

查询单个数据资产。

asset = client.get_asset("asset-001")
print(asset.name, asset.status, f"已发行 {asset.total_shares} 份")

`get_shares(asset_id) -> list[ShareHolder]`

列出数据资产的所有持有人。

holders = client.get_shares("asset-001")
for h in holders:
    print(f"{h.address}: {h.shares} 份")

`get_bonding_curve(asset_id) -> BondingCurve`

查询联合曲线状态（供应量、储备金、现价）。

bc = client.get_bonding_curve("asset-001")
print(f"现价: {bc.spot_price_uoas} uoas, 储备: {bc.reserve_uoas} uoas")

`get_access_level(asset_id, address) -> AccessLevel`

查询地址在数据资产上的访问等级（L0-L3）。

al = client.get_access_level("asset-001", "oasyce1buyer...")
print(f"等级: {al.level}, 持股: {al.equity_bps} bps")

`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]`

查询资产的子版本（fork）。

`get_datarights_params() -> dict`

查询数据权益模块参数。

结算 (Settlement)

`get_escrow(escrow_id) -> Escrow`

按 ID 查询托管。

esc = client.get_escrow("esc-001")
print(esc.status)  # LOCKED, RELEASED, REFUNDED, EXPIRED

`list_escrows(creator) -> list[Escrow]`

列出某地址创建的所有托管。

escrows = client.list_escrows("oasyce1abc...")
locked = [e for e in escrows if e.status == "LOCKED"]

`get_settlement_params() -> dict`

查询结算模块参数。

信誉 (Reputation)

`get_reputation(address) -> Reputation`

查询地址的信誉分。

rep = client.get_reputation("oasyce1abc...")
print(f"评分: {rep.score}, 来自 {rep.total_feedback} 次反馈")

`get_leaderboard() -> list[Reputation]`

获取信誉排行榜。

lb = client.get_leaderboard()
for entry in lb[:5]:
    print(f"{entry.address}: {entry.score}")

`get_reputation_params() -> dict`

查询信誉模块参数。

工作证明 (Proof of Useful Work)

`get_task(task_id) -> Task`

按 ID 查询计算任务。

task = client.get_task("42")
print(task.status, task.bounty_uoas)

`list_tasks(status=None) -> list[Task]`

按状态过滤任务（1=已提交, 2=已分配, ..., 5=已结算）。

pending = client.list_tasks(status=1)

`list_executors() -> list[Executor]`

列出所有已注册的执行者。

for ex in client.list_executors():
    print(f"{ex.address}: 已完成 {ex.tasks_completed} 个任务, 活跃={ex.active}")

`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`

查询工作模块参数和纪元统计。

注册 (Onboarding)

`get_registration(address) -> Registration`

查询用户的注册信息。

reg = client.get_registration("oasyce1new...")
print(f"空投: {reg.airdrop_amount} uoas, 已还: {reg.repaid_amount} uoas")

`get_debt(address) -> Debt`

查询未偿还的注册债务。

debt = client.get_debt("oasyce1new...")
print(f"剩余: {debt.remaining} uoas ({debt.status})")

`get_onboarding_params() -> dict`

查询注册模块参数（PoW 难度、空投金额等）。

银行 / 账户 / 区块 (Cosmos SDK)

`get_balance(address) -> Balance`

查询 uoas 余额。

bal = client.get_balance("oasyce1abc...")
print(f"{bal.amount_oas} OAS ({bal.amount_uoas} uoas)")

`get_account(address) -> Account`

查询账户号和序列号（签名交易时需要）。

acct = client.get_account("oasyce1abc...")
print(f"账户 #{acct.account_number}, 序列 {acct.sequence}")

`get_latest_block() -> Block`

查询最新区块。

block = client.get_latest_block()
print(f"高度 {block.height}, 链 {block.chain_id}")

PoW 求解器

`solve_pow(address, difficulty=16) -> PowResult`

纯 Python PoW 求解器，与链上 Go 验证器完全一致。

result = OasyceClient.solve_pow("oasyce1abc...", difficulty=16)
print(f"Nonce: {result.nonce}, 尝试: {result.attempts} 次")

# 然后注册
tx = client.build_self_register("oasyce1abc...", result.nonce)

交易构建器 (27 个)

所有 build_* 方法生成未签名的 Cosmos SDK 交易 JSON。签名后传给 broadcast_tx() 广播。

能力市场

方法	说明
`build_register_capability(sender, name, endpoint, price_uoas, ...)`	注册 AI 能力
`build_invoke_capability(sender, capability_id, input_data)`	调用能力（自动托管）
`build_complete_invocation(sender, invocation_id, output_hash, usage_report)`	提交输出（开始挑战窗口）
`build_fail_invocation(sender, invocation_id)`	标记调用失败
`build_claim_invocation(sender, invocation_id)`	挑战窗口后领取付款
`build_dispute_invocation(sender, invocation_id, reason)`	挑战窗口内争议

数据权益

方法	说明
`build_register_asset(sender, name, content_hash, ...)`	注册数据资产
`build_buy_shares(sender, asset_id, amount_uoas)`	买入股份（Bancor 曲线）
`build_sell_shares(sender, asset_id, shares)`	卖出股份（反向曲线）
`build_file_dispute(sender, asset_id, reason, evidence, remedy)`	提起争议
`build_initiate_shutdown(sender, asset_id)`	发起关停（7天冷却期）
`build_claim_settlement(sender, asset_id)`	关停后按比例领取储备金
`build_create_migration(sender, source_id, target_id, rate_bps, max_shares)`	创建迁移路径
`build_migrate(sender, source_id, target_id, shares)`	执行跨版本迁移

结算

方法	说明
`build_create_escrow(sender, amount_uoas, capability_id, asset_id)`	创建托管
`build_release_escrow(sender, escrow_id)`	释放托管（90/5/2/3 分账）
`build_refund_escrow(sender, escrow_id)`	退款托管

信誉

方法	说明
`build_submit_feedback(sender, invocation_id, rating, comment)`	提交评价（0-500）
`build_report_misbehavior(sender, target, evidence_type, evidence)`	举报不良行为

工作证明 (PoUW)

方法	说明
`build_register_executor(sender, task_types, max_cu)`	注册执行者
`build_update_executor(sender, task_types, max_cu, active)`	更新执行者
`build_submit_task(sender, task_type, input_hash, input_uri, max_cu, bounty_uoas)`	提交计算任务
`build_commit_result(sender, task_id, commit_hash)`	提交结果承诺
`build_reveal_result(sender, task_id, output_hash, output_uri, cu_used, salt)`	揭示结果
`build_dispute_result(sender, task_id, reason, bond_uoas)`	争议结果

注册

方法	说明
`build_self_register(sender, nonce)`	PoW 自注册
`build_repay_debt(sender, amount_uoas)`	偿还空投债务

`broadcast_tx(signed_tx) -> TxResult`

广播已签名交易。

result = client.broadcast_tx(signed_tx)
if result.success:
    print(f"TX 哈希: {result.tx_hash}")
else:
    print(f"失败 (code {result.code}): {result.raw_log}")

工具方法

`health() -> bool`

检查节点是否可达。

if client.health():
    print("节点运行中")

`oas_to_uoas(oas) -> int` / `uoas_to_oas(uoas) -> float`

OAS 和 micro-OAS 之间转换。1 OAS = 1,000,000 uoas。

OasyceClient.oas_to_uoas(1.5)     # 1500000
OasyceClient.uoas_to_oas(2500000)  # 2.5

AHRP 适配器（v0.3.0）

SigningBridge 将 SDK 的 TX 构建器与 oasyced CLI 签名结合，实现一步到位的交易广播：

from oasyce_sdk import OasyceClient, SigningBridge

client = OasyceClient("http://localhost:1317")
bridge = SigningBridge(
    client=client,
    oasyced_path="./oasyced",
    key_name="my-agent",
    chain_id="oasyce-testnet-1",
    node="tcp://localhost:26657",
)

# 构建 + 签名 + 广播
result = bridge.create_escrow(amount_uoas=50000, asset_id="DATA_001")
print(result.tx_hash, result.success)

AhrpChainAdapter 将 SigningBridge 适配为 Plugin Engine AHRP Executor 期望的接口，无需修改任何 AHRP 代码：

from oasyce_sdk import AhrpChainAdapter

adapter = AhrpChainAdapter(bridge)
# 直接传入 AHRP Executor:
# executor = AHRPExecutor(chain_client=adapter)

完整示例见 examples/ahrp_two_agent_demo.py。

错误处理

所有错误继承自 OasyceError，可以宽泛或精确地捕获：

from oasyce_sdk import OasyceClient
from oasyce_sdk.errors import NotFoundError, TimeoutError, OasyceError

client = OasyceClient()

try:
    cap = client.get_capability("cap-xyz")
except NotFoundError:
    print("能力不存在")
except TimeoutError:
    print("节点响应慢")
except OasyceError as e:
    print(f"出错了: {e}")

异常层级：

OasyceError
  +-- NotFoundError      # 链上未找到资源 (404 / gRPC NOT_FOUND)
  +-- ChainError         # 应用层链错误
  +-- HTTPError          # 非预期 HTTP 状态码
  +-- ConnectionError    # 无法连接节点
  +-- TimeoutError       # 请求超时
  +-- ValidationError    # 请求发出前的输入校验错误

为什么不直接用 `requests`？

你当然可以直接请求 http://localhost:1317/oasyce/capability/v1/capabilities。这个 SDK 额外提供：

类型化响应 —— 编辑器自动补全，不用猜 JSON key
异常层级 —— 区分 NotFoundError / TimeoutError / ChainError
单位转换 —— 内置 oas_to_uoas() / uoas_to_oas()
Protobuf 枚举映射 —— ESCROW_STATUS_LOCKED 自动变成 "LOCKED"
交易构建器 —— 正确的消息结构，不需要读 proto 文件
线程安全 —— 无全局状态，内部使用 requests.Session
单一依赖 —— 只需 requests>=2.28，无需编译 protobuf

生态链接

oasyce-chain — L1 链（Go / Cosmos SDK），公测文档见 docs/PUBLIC_BETA_CN.md
Plugin Engine — Python CLI + Dashboard + DataVault（pip install oasyce）
Discord

协议

Apache-2.0

oasyce

Quick Install

oasyce-sdk

安装

MCP Server

LangChain Tools

快速开始（SDK）

API 参考

构造函数

能力市场 (Capability Marketplace)

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

数据资产 (Data Assets)

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

结算 (Settlement)

get_escrow(escrow_id) -> Escrow

list_escrows(creator) -> list[Escrow]

get_settlement_params() -> dict