oasyce

oasyce-sdk

Oasyce スタックのランタイム／ボディです。ローカルのアイデンティティバインディングを解決し、wallet を製品の中心的な概念にするのではなく、同じデリゲート実行コンテキストを Chain、Thronglets、Psyche に接続します。

Oasyce スタックのランタイム／ボディです。ローカルのアイデンティティバインディングを解決し、wallet を製品のオントロジーの中心にするのではなく、同じデリゲート実行コンテキストを Chain、Thronglets、Psyche に接続します。

英語 | API リファレンス／完全版 API ドキュメント

---

スタックの役割

• Sigil：連続性とライフサイクルの構文であり、巨大なランタイムオブジェクトではありません
• oasyce-sdk：ボディと実行面です。ローカルバインディング、署名者、ツールの入口、レイヤー間のブリッジを担当します
• Oasyce Chain：認可の真実、コミットメント、決済、パブリックな最終性
• Thronglets：共有環境、デリゲートの連続性、トレース／シグナル／プレゼンス
• Psyche：主観的な連続性、自己状態、関係の残留

したがって、SDK の第一原則は、まず統一されたローカル実行 ID を解決し、それを各レイヤーに投影することです。

単独での導入

oasyce-sdk は、スタック全体を使うための前提条件ではありません。

• Psyche だけを使う場合、sdk は不要です
• Thronglets だけを使う場合、sdk は不要です
• Oasyce Chain の CLI／REST／gRPC を直接呼び出すだけの場合も、sdk は不要です
• ローカルのデリゲートランタイムを、オンチェーンの認可／決済経路に接続する場合にのみ、sdk が主要な経路に加わります

そのため、最も自然な導入順序は、まずいずれかのレイヤーを単独で使い、その後必要に応じてバインディングとチェーン決済を追加することです。最初から統合エントリーポイントをインストールする必要はありません。

---

フルスタックの一括セットアップ

完全な環境（Thronglets + Psyche + SDK + Chain）を使いたいですか？コマンドは 1 つです。

完全な環境（Thronglets + Psyche + SDK + Chain）を使いたいですか？コマンドは 1 つです。

curl -fsSL https://raw.githubusercontent.com/Shangri-la-0428/oasyce-sdk/main/scripts/bootstrap.sh | bash

環境の確認 → Thronglets のインストール → Psyche のインストール → SDK のインストール → oasyce start の実行による統合オーケストレーションを順に行います。いずれかのレイヤーで失敗しても、ほかのレイヤーは停止しません。

前提条件：Node.js >= 22 + Python >= 3.10

---

統一エントリーポイント

各レイヤーをすでに個別にインストールしている場合、または SDK だけが必要な場合のデフォルトの入口は次のとおりです。

各レイヤーをすでに個別にインストールしている場合、または SDK だけが必要な場合：

pip install oasyce-sdk
oasyce start

このマシンが別のデバイスから handoff ファイルを受け取る側である場合、または既存の環境に参加することが明らかな場合は、最初に start を実行しないでください。代わりに、次をデフォルトの入口として使います。

oasyce join

簡単な使い分け：

• 最初のデバイス／handoff なし：oasyce start
• 2 台目のデバイス／handoff ファイルあり：oasyce join

このマシンに以前の oasyce／oasyce-net パッケージがインストールされていて、oasyce が依然として ModuleNotFoundError: No module named 'oasyce' を返す場合は、古いエントリーポイントを削除してから再インストールしてください。

python3 -m pip uninstall -y oasyce oasyce-sdk
python3 -m pip install --user -U oasyce-sdk

Python が externally managed の場合は、--break-system-packages を追加するか、pipx install oasyce-sdk を使ってください。

渡されたものが handoff ファイルではなく、このリポジトリの git リンクの場合は、開発指示ではなくロケーターとして扱ってください。デフォルトの操作は次のとおりです。

python3 -m pip install --user -U "git+https://github.com/Shangri-la-0428/oasyce-sdk.git"
oasyce start

別のデバイスから接続を受けるマシンの場合は、2 つ目の手順を次のように置き換えてください。

oasyce join

ユーザーがソースの開発やデバッグを明示的に求めていない限り、デフォルトで git clone とソースからのローカルインストールを行わないでください。

次の処理をできる限り自動で行います。

1. ローカルの署名者／バインディングを再利用するか、新規作成します
2. デフォルトのエージェント設定を生成します
3. Thronglets のブートストラップに接続します
4. Psyche MCP サーフェスを設定します
5. ローカルの oasyce-agent を起動します

通常、質問されるのはアイデンティティがない場合の New / Recover だけです。

マルチデバイスの手順も、同じ一連のコマンドにまとめられています。

oasyce share
oasyce join ~/Desktop/oasyce-connection.json
oasyce status

oasyce share はデフォルトで接続ファイルを ~/Desktop/oasyce-connection.json に書き込みます。--output で変更することもできます。 このファイルは自己説明型になりました。「これは handoff アーティファクトです」と明記し、preferred_surface を宣言します。完全な Oasyce 環境では、通常 oasyce join <connection-file> を推奨します。メインデバイスに最小限の Thronglets インストールしかない場合は、自然に thronglets join <connection-file> に戻ります。

ここで oasyce が Thronglets の実行面を独自に推測することはありません。Thronglets が書き込んだ標準の管理ランタイムを優先します。

~/.thronglets/bin/thronglets-managed

この実行面が古すぎる場合、oasyce share は古いプロトコルで続行するのではなく、先に更新するよう直接求めます。通常の修復方法は 1 つだけです。

thronglets setup

Thronglets のデータディレクトリを意図的にデフォルト以外の場所に配置している場合は、追加で次をエクスポートしてください。

export THRONGLETS_DATA_DIR=/path/to/thronglets-data

これは統一エントリーポイントであり、各製品の独立性は変わりません。引き続き Psyche、Thronglets、Chain を個別に使用できます。

---

AI エージェント向けクイックスタート

あなたは AI エージェントですか？ 次のコードを順番に実行すれば、Oasyce チェーンを操作できます。設定ファイルは不要で、人間のサポートも必要ありません。

あなたは AI エージェントですか？ 次のコードブロックを順番に実行してください。設定ファイルも、人間のサポートも必要ありません。

ステップ 1：インストール

pip install oasyce-sdk

ステップ 2：まず適切な経路を選ぶ

次に該当する場合：

• 最初のデバイス：以下の Wallet.create() の手順に進みます
• 別のデバイスから handoff ファイルを受け取る場合：先に oasyce join を実行し、署名者を新規作成しないでください
• 古い署名者／ニーモニックのみがあり、handoff ファイルがない場合：oasyce start を実行し、エントリーポイントで Recover を選択します

ステップ 3：ローカル署名者の作成とテストトークンの取得

import requests
from oasyce_sdk import OasyceClient
from oasyce_sdk.crypto import Wallet, NativeSigner

# 首次设备 / first device
wallet = Wallet.create()
print(f"地址: {wallet.address}")
print(f"助记词(保存好): {wallet.mnemonic}")

# 之后的运行、MCP、LangChain、runtime 集成优先复用本机 binding:
# wallet = Wallet.auto()  # OASYCE_MNEMONIC > ~/.oasyce/wallet.json

# 领测试币（免费，每次 20 OAS）/ get free testnet tokens
resp = requests.get(f"http://47.93.32.88:8080/faucet?address={wallet.address}")
print(resp.json())  # {"status": "ok", "amount": "20 OAS", ...}

# 连接链 / connect
client = OasyceClient("http://47.93.32.88:1317")
signer = NativeSigner(wallet, client, chain_id="oasyce-testnet-1")

ここでの wallet は署名者の情報であり、アイデンティティの全体を表す概念ではありません。デフォルトの製品経路は、ニーモニックを起点とする考え方ではなく、ローカルバインディングを起点にするべきです。

初めてオンチェーンへの書き込みを行う際、SDK はこの最初のデバイスを自動的にルートプリンシパルとして扱い、共有デリゲートポリシーをローカルに書き込みます。同じ所有者が使う以降のデバイスは、Thronglets の share / join またはローカルポリシーのブートストラップを通じて接続するだけで、自動的に登録されます。手動で set-policy を実行する必要はありません。

ステップ 4：操作を開始する

# 查余额 / check balance
bal = client.get_balance(wallet.address)
print(f"余额: {bal.amount_oas} OAS")

# 注册数据资产 / register a data asset
result = signer.register_asset(
    name="My Analysis Report",
    content_hash="sha256-of-your-data",
    tags=["analysis", "finance"],
    description="Q4 financial analysis",
)
print(f"TX: {result.tx_hash}, 成功: {result.success}")

# 注册 AI 能力 / register an AI capability
signer.register_capability(
    name="Translation Service",
    endpoint="https://my-api.com/translate",
    price_uoas=500_000,  # 0.5 OAS per call
    tags=["nlp", "translation"],
)

# 买数据资产股份 / buy shares of a data asset
signer.buy_shares("DATA_0000000000000001", amount_uoas=1_000_000)

# 查看信誉 / check reputation
rep = client.get_reputation(wallet.address)
print(f"信誉分: {rep.score}")

Step 5（任意）：複数デバイス／複数エージェントで1つのアカウントを共有する

# 正常路径：
# 1) 第一台设备第一次写链时，自动成为 root principal，并生成本地 delegate policy
# 2) 之后第二台设备通过 Thronglets share/join 或本地 policy bootstrap 接入
# 3) SDK 会在第一次写链时自动 enroll，并开始用 MsgExec 代理执行

# 高级回退（一般不需要）:
signer.set_delegate_policy(
    token="shared-secret",
    allowed_msgs=["/oasyce.datarights.v1.MsgBuyShares"],
    per_tx_uoas=1_000_000,
    window_uoas=10_000_000,
)

---

すべての機能の概要

オンチェーンメッセージ（37種類）

モジュール	操作
datarights	register_asset, buy_shares, sell_shares, delist_asset
capability	register_capability, invoke_capability, complete_invocation, claim_invocation, dispute_invocation
reputation	submit_feedback
work	submit_task, register_executor, assign_task, submit_result, approve_result
onboarding	self_register (PoW), send_coins
delegate	set_delegate_policy, enroll_delegate, revoke_delegate, delegate_exec
anchor	anchor_trace, anchor_batch
settlement	(内部：エスクローの作成／解放／返金。他のモジュールで使用)
halving	(自動：ブロック報酬と半減期スケジュール)

クエリ（読み取り専用）

client = OasyceClient("http://47.93.32.88:1317")

# 资产 / Assets
client.get_data_asset("DATA_...")           # 单个资产详情
client.list_data_assets()                   # 所有资产列表
client.get_shareholders("DATA_...")         # 股东列表
client.get_access_level("DATA_...", addr)   # 访问权限等级

# 能力 / Capabilities
client.list_capabilities()                  # 所有能力
client.list_capabilities(tag="llm")         # 按标签筛选
client.get_capability("CAP_...")            # 单个能力详情

# 信誉 / Reputation
client.get_reputation(addr)                 # 信誉分

# 委托 / Delegate
client.get_delegate_policy(principal)       # 查看委托政策
client.get_delegates(principal)             # 列出所有代理
client.get_delegate_spend(principal)        # 查看花费窗口
client.get_principal(delegate)              # 反查：代理→委托人

# 工作 / Work
client.get_task("TASK_...")                 # 任务详情

# 通用 / General
client.get_balance(addr)                    # 余额
client.get_latest_block()                   # 最新区块
client.health()                             # 节点健康检查

---

Testnet 情報

項目	値
Chain ID	oasyce-testnet-1
REST API	http://47.93.32.88:1317
RPC	http://47.93.32.88:26657
gRPC	47.93.32.88:9090
水栓	http://47.93.32.88:8080/faucet?address=YOUR_ADDRESS
Token	uoas (1 OAS = 1,000,000 uoas)

---

インストールオプション

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

---

エージェントランタイム

フィードバックループ：集合知を生み出します。 2つのメソッドでループを閉じます。perceive() は集合体を読み取り、act() は集合体に書き込みます。

集合知のためのフィードバックループです。2つのメソッドでループを閉じます。perceive() は集合体を読み取り、act() は集合体に書き戻します。

from oasyce_sdk.agent.runtime import AgentRuntime

agent = AgentRuntime()

# 读集体经验 + 情绪状态 / read collective experience + emotional state
perception = agent.perceive("分析金融数据")
# perception.capabilities → 集体能力统计
# perception.kernel       → 情绪内核 (vitality, tension, warmth, guard)

# 写回结果 / write outcome back
agent.act("分析了 Q4 营收", "succeeded", "金融分析", capability="data-analysis")
# → Thronglets 记录痕迹 → Psyche 接收 trust_up

Psyche / Thronglets が利用できない場合は、適切に機能を縮退します。oasyce-agent デーモンは、スキャンのたびに自動で perceive/act に参加します。

MCP ネイティブの AI ツール（Claude Code / Cursor / Codex）は、AgentRuntime を使わずに Thronglets MCP の substrate_query / trace_record を直接利用できます。ワンクリックで設定できます。

thronglets bootstrap    # 自动检测本机 AI 工具并写入适配层配置

---

データエージェント

1つのコマンドで、データ資産の権利を自動的に確立します。 バックグラウンドデーモンが、本機での identity binding を一度完了してから、ローカルファイルをスキャンし、プライバシーを検出し、SHA256 でハッシュ化して、オンチェーンに登録します。macOS / Linux / Windows に対応しています。

1つのコマンドで、データ資産を自動管理します。バックグラウンドデーモンがファイルをスキャンし、個人情報を検出して、ハッシュ化し、オンチェーンに登録します。

oasyce start                       # 默认前门：接好本地栈并启动 agent
oasyce status                      # 统一查看本机 stack 状态
oasyce-agent status                # 仅查看 data-agent 运行状态 + 已注册资产数
oasyce-agent stop                  # 停止
oasyce-agent scan ~/Documents      # 手动扫描（分类 + 隐私报告）
oasyce-agent privacy ~/secret.csv  # 单文件 PII 检查
oasyce-agent stats                 # 资产统计

プライバシーゲート（厳守）：privacy_risk == "safe" のファイルのみを自動登録します。メールアドレス、携帯電話番号、身分証番号、銀行カード、API キーは自動的にブロックされます。

設定ファイル：~/.oasyce/agent.json（自動生成されます。スキャンパスや間隔などは手動で編集できます）。

---

MCP サーバー

AI アシスタント（Claude Desktop / Cursor / Windsurf）から Oasyce チェーンを直接操作できます。32個のツール（読み取り＋書き込み）を利用できます。

AI アシスタントが Oasyce チェーンを直接操作するための32個のツールです。

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

書き込みツールは、デフォルトで本機の binding を再利用します：~/.oasyce/identity.v1.json + ~/.oasyce/wallet.json。先に Thronglets を使用した場合、SDK は初回のローカルバインディング時に、~/.thronglets/identity.v1.json 内の owner_account をアカウントヒントとして任意で取り込めます。OASYCE_MNEMONIC は、ステートレス環境またはサーバー環境で明示的に上書きする場合にのみ使用します。集合知（perceive/act）には Thronglets MCP を使用します。Thronglets のデフォルトの接続方法は thronglets bootstrap ですが、oasyce start を直接実行することもできます。

---

LangChain ツール

from oasyce_sdk.langchain_tools import oasyce_tools  # 18 个工具（8 读 + 10 写）
from langchain.agents import create_react_agent

agent = create_react_agent(llm, oasyce_tools)
agent.invoke({"input": "注册一个 AI 翻译服务，0.5 OAS/次"})

書き込みツールは、デフォルトで本機の binding を再利用します。OASYCE_MNEMONIC が必要なのは、ステートレスランタイムの場合のみです。読み取り専用：from oasyce_sdk.langchain_tools import oasyce_read_tools

---

エラー処理

すべてのエラーは 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 を直接使わないのか？

• 型付きレスポンス — エディターの自動補完を利用でき、JSON のキーを推測する必要がありません
• 例外階層 — NotFoundError / TimeoutError / ChainError を区別できます
• 単位変換 — oas_to_uoas() / uoas_to_oas()
• トランザクションビルダー — proto ファイルを読む必要がなく、正しいメッセージ構造を構築できます
• スレッドセーフ — グローバル状態を使わず、内部で requests.Session を使用します
• 軽量な依存関係 — protobuf ライブラリや Go バイナリは不要で、requests + coincurve + mnemonic のみを使用します

---

エコシステム

• oasyce-chain — L1 アプリチェーン（Go / Cosmos SDK）
• Thronglets — P2P 集合記憶基盤
• Psyche — AI 自己状態カーネル
• Discord

ライセンス

Apache-2.0