# oasyce-sdk

Python SDK for the Oasyce L1 chain — agent-native settlement infrastructure where AI agents own property, enforce contracts, and resolve disputes autonomously.

## Install

    pip install oasyce-sdk

## Quick Start

    from oasyce_sdk import OasyceClient
    client = OasyceClient("http://localhost:1317")

## OasyceClient Methods (35 queries + 27 TX builders)

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

### Reputation
- get_reputation(address) -> Reputation
- get_leaderboard() -> list[Reputation]
- get_reputation_params() -> dict

### Work (Proof of Useful Work)
- 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

### Onboarding
- get_registration(address) -> Registration
- get_debt(address) -> Debt
- get_onboarding_params() -> dict

### Bank / Auth / Block (Cosmos SDK)
- get_balance(address) -> Balance
- get_account(address) -> Account
- get_latest_block() -> Block

### PoW Solver
- solve_pow(address, difficulty=16) -> PowResult  # pure-Python, matches Go verifier

### Transaction Builders (27 total)
- build_register_capability(sender, name, endpoint, price_uoas, tags=None) -> dict
- build_invoke_capability(sender, capability_id, input_data=None) -> dict
- build_complete_invocation(sender, invocation_id, output_hash, usage_report) -> dict
- build_fail_invocation(sender, invocation_id) -> dict
- build_claim_invocation(sender, invocation_id) -> dict
- build_dispute_invocation(sender, invocation_id, reason) -> dict
- build_register_asset(sender, name, content_hash, tags=None) -> dict
- build_buy_shares(sender, asset_id, amount_uoas) -> dict
- build_sell_shares(sender, asset_id, shares) -> dict
- build_file_dispute(sender, asset_id, reason, evidence, remedy) -> dict
- build_initiate_shutdown(sender, asset_id) -> dict
- build_claim_settlement(sender, asset_id) -> dict
- build_create_migration(sender, source_id, target_id, rate_bps, max_shares) -> dict
- build_migrate(sender, source_id, target_id, shares) -> dict
- build_create_escrow(sender, amount_uoas, capability_id, asset_id) -> dict
- build_release_escrow(sender, escrow_id) -> dict
- build_refund_escrow(sender, escrow_id) -> dict
- build_submit_feedback(sender, invocation_id, rating, comment) -> dict
- build_report_misbehavior(sender, target, evidence_type, evidence) -> dict
- build_register_executor(sender, task_types, max_cu) -> dict
- build_update_executor(sender, task_types, max_cu, active) -> dict
- build_submit_task(sender, task_type, input_hash, input_uri, max_cu, bounty_uoas) -> dict
- build_commit_result(sender, task_id, commit_hash) -> dict
- build_reveal_result(sender, task_id, output_hash, output_uri, cu_used, salt) -> dict
- build_dispute_result(sender, task_id, reason, bond_uoas) -> dict
- build_self_register(sender, nonce) -> dict
- build_repay_debt(sender, amount_uoas) -> dict
- broadcast_tx(signed_tx) -> TxResult

### Utility
- health() -> bool
- oas_to_uoas(oas) -> int
- uoas_to_oas(uoas) -> float

## NativeSigner (v0.4.0)

Pure-Python signer — build + sign + broadcast in one call, zero Go dependency:

    from oasyce_sdk import OasyceClient
    from oasyce_sdk.crypto import Wallet, NativeSigner
    wallet = Wallet.create()
    signer = NativeSigner(wallet, client, chain_id="oasyce-testnet-1")
    result = signer.create_escrow(amount_uoas=50000, asset_id="DATA_001")

Methods: create_escrow, release_escrow, refund_escrow, register_capability,
invoke_capability, complete_invocation, claim_invocation, submit_feedback,
register_asset, buy_shares, self_register, broadcast(tx_body)

## Types (21 frozen dataclasses)

Capability, Earnings, DataAsset, ShareHolder, BondingCurve, Escrow,
Reputation, Task, Executor, Registration, Debt, Balance, Account, Block,
TxResult, Invocation, AccessLevel, Dispute, MigrationPath, EpochStats, PowResult

## Error Hierarchy

OasyceError
  NotFoundError      — 404 / gRPC NOT_FOUND
  ChainError         — application-level chain error
  HTTPError          — unexpected HTTP status
  ConnectionError    — cannot reach node
  TimeoutError       — request timed out
  ValidationError    — bad input before request sent

## Key Concepts

- OAS: protocol token. 1 OAS = 1,000,000 uoas
- Bonding Curve: tokens = supply * ((1 + payment/reserve)^0.5 - 1), CW=0.5
- Fee Split: 90% provider, 5% treasury, 3% validator, 2% burn
- Access Levels: >=0.1% L0, >=1% L1, >=5% L2, >=10% L3
- AHRP: Agent Handshake Routing Protocol — ANNOUNCE/REQUEST/OFFER/ACCEPT/DELIVER/CONFIRM
- PoW: sha256(address_bytes || nonce_le_uint64) with leading zero bits check

## Links

- Chain: https://github.com/Shangri-la-0428/oasyce-chain
- SDK: https://github.com/Shangri-la-0428/oasyce-sdk
- oasyce-net (CLI + Dashboard): https://github.com/Shangri-la-0428/oasyce-net
- Discord: https://discord.gg/tfrCn54yZW
