Python

其他 Python SDK 在上游工作空間中是 iroha-python. 第一個. Iroha 3 釋放目標 Torii 和 Norito 嵌入您的集成所使用的包裝版本或源修改,以便 SDK 和節點保持在相同的電線格式修改.

下面的僅可閱讀示例與公衆 Taira 在 https://taira.sora.org 進行了檢查. 轉換示例是交易模板:它們需要一個真正的 Taira 權威,私鑰,氣體元數據和任何目標路線要求的運營商代幣才能提交.

使用如下順序的例子:

階段	與公衆競爭 Taira?	你需要什麼?
只有讀取的客戶通話	是的.	Python 包加上網絡接入
地方簽名和指令建設者	在 `submit()`之前,沒有網絡通話.	你的原始擴展和關鍵材料
移動交易和服務調用	只有你自己的資金賬戶	權威機構賬戶,私鑰,鏈 ID,費用元數據,費用資產餘額和路線代幣
連接框架編碼器,加密和 GPU 助手	只有本地	GPU 助手也需要一個能夠使用 CUDA 的後端

安裝

包裝元數據名稱是 iroha-python.不要假設一個未插入的 PyPI 安裝與現場 Taira 網絡相匹配.安裝從相同的上游修改構建的輪或源檢查,您的集成目標:

bash

python -m pip install /path/to/iroha_python-*.whl

如果您的項目直接消耗上游工作空間, Python 在運行使用例之前,建立本地擴展 Instruction, TransactionDraft, 簽名,加密, SoraFS 原住民的援助者, GPU 使用從上游構建命令. python/iroha_python/README.md, 然後檢查本土出口負載:

bash

cd python/iroha_python
python - <<'PY'
from iroha_python import Instruction, generate_ed25519_keypair

print(Instruction)
print(generate_ed25519_keypair().public_key.hex())
PY

如果create_torii_client進口但 Instruction或 generate_ed25519_keypair未成功,則純的 Python 包裝可用,但本地擴展不存在.

快速開始

開始使用公開,僅可閱讀的 Taira 終端點:

python

from iroha_python import (
    create_torii_client,
)

client = create_torii_client("https://taira.sora.org")

# Public reads do not need an authority or private key.
status = client.request_json("GET", "/status", expected_status=(200,))
accounts = client.list_accounts_typed(limit=5)

print(status["build"]["version"])
for account in accounts.items:
    print(account.id)

分享的設置

在提交之前,請使用此設置用於突變模板. 取代您的部署中的每個位置持有者以 Taira 權威,私鑰,令牌和資產/賬戶 IDs.

authority是簽署交易的賬戶. private_key必須與該帳戶匹配, CHAIN_ID必須與目標網絡匹配,並且TX_METADATA必須包含網絡預期的費用字段.下面的位置持有者故意無效,因此它們不是偶然提交.

python

from iroha_python import (
    Ed25519KeyPair,
    Instruction,
    TransactionConfig,
    TransactionDraft,
    create_torii_client,
)

TORII_URL = "https://taira.sora.org"
CHAIN_ID = "fc56984b-2be7-431d-840e-21514d1883f0"
AUTH_TOKEN = None

# Replace these placeholders with the real signing keys for your accounts.
alice_pair = Ed25519KeyPair.from_private_key(bytes.fromhex("<alice-private-key-hex>"))
bob_pair = Ed25519KeyPair.from_private_key(bytes.fromhex("<bob-private-key-hex>"))

# The authority string must identify the same account as the private key.
alice = "<alice-account-id>"
bob = "<bob-account-id>"

ROSE_DEFINITION = "rose#wonderland"
ROSE_ASSET = "<rose-asset-id>"
BADGE_NFT = "badge$wonderland"

TX_METADATA = {
    # Public Taira fee asset. Use the configured XOR asset on your network.
    "gas_asset_id": "6TEAJqbb8oEPmLncoNiMRbLEK6tw",
}

client = create_torii_client(TORII_URL, auth_token=AUTH_TOKEN)


def submit(*instructions):
    # This is the network boundary: build, sign, submit, and wait for status.
    return client.build_and_submit_transaction(
        chain_id=CHAIN_ID,
        authority=alice,
        private_key=alice_pair.private_key,
        instructions=list(instructions),
        metadata=TX_METADATA,
        wait=True,
    )

Instruction.*只調用構建指令的有效載荷. submit()是 SDK 簽署交易,發送到 Torii 並等待狀態的地點.

費用和天然氣

在 Taira 中,費用資產由公共水龍頭提供資金,交易轉賬數據必須包含 gas_asset_id.在 Minamoto 上,費用以真實 XOR 支付,而資產 ID 來自該網絡配置.

費用元數據屬於交易,而不是單個說明.上面的 submit()輔助員將 TX_METADATA 附加到它構建的每個交易中:

python

TX_METADATA = {
    # Taira expects the fee asset definition in transaction metadata.
    "gas_asset_id": "6TEAJqbb8oEPmLncoNiMRbLEK6tw",
}

envelope, status = client.build_and_submit_transaction(
    chain_id=CHAIN_ID,
    authority=alice,
    private_key=alice_pair.private_key,
    # Fee metadata is attached to the transaction, not the instruction.
    instructions=[
        Instruction.set_account_key_value(
            alice,
            "python_fee_example",
            "ready",
        )
    ],
    metadata=TX_METADATA,
    wait=True,
)

在發送信件之前,請確保權威賬戶擁有足夠的費用資產. 精確的龍頭和資產 ID 是網絡特定的;這是 Taira 形狀:

python

FEE_ASSET_DEFINITION = "6TEAJqbb8oEPmLncoNiMRbLEK6tw"
# The faucet returns the concrete account asset ID to check here.
FEE_ASSET_ID = "<fee-asset-id-from-faucet-response>"
TX_METADATA = {"gas_asset_id": FEE_ASSET_DEFINITION}

# Fail before submitting if the signer cannot pay gas.
fee_assets = client.list_account_assets_typed(
    alice,
    limit=10,
    asset_id=FEE_ASSET_ID,
)
if not fee_assets.items:
    raise RuntimeError("fund the authority account with the Taira fee asset first")

龍頭返回用於餘額檢查的混凝土 asset_id.gas_asset_id元數據領域使用費用資產定義 ID.

在構建交易時,將應用程序元數據與費用元數據分開,併合並地圖:

python

APP_METADATA = {"source": "python-docs"}
# Merge app metadata with required fee metadata before building the draft.
metadata = {**TX_METADATA, **APP_METADATA}

draft = TransactionDraft(
    TransactionConfig(
        chain_id=CHAIN_ID,
        authority=alice,
        metadata=metadata,
    )
)

如果您省略了費用元數據,使用錯誤的費用資產,或與未經融資的帳戶簽署,一個真正的網絡應該拒絕交易,即使指令有效載荷是否有效的.

Taira - 檢查的僅閱讀通話

這些呼叫成功地回覆了公衆 Taira:

python

client = create_torii_client("https://taira.sora.org")

# Use raw requests for endpoints that do not need a typed wrapper.
status = client.request_json("GET", "/status", expected_status=(200,))
parameters = client.request_json("GET", "/v1/parameters", expected_status=(200,))

# Typed helpers parse pagination and records into dataclasses.
accounts = client.list_accounts_typed(limit=1)
domains = client.list_domains_typed(limit=1)
definitions = client.query_asset_definitions_typed(limit=1)

# These calls inspect live node subsystems without mutating state.
time_now = client.get_time_now_typed()
time_status = client.get_time_status_typed()
sumeragi = client.get_sumeragi_status_typed()
connect = client.get_connect_status_typed()

print(status["build"]["version"])
print(parameters["sumeragi"]["block_time_ms"])
print(accounts.total, domains.total, definitions.total)
print(time_now.now_ms, len(time_status.samples), sumeragi.leader_index)
print(connect.enabled, connect.sessions_active)

航線如 /v1/status, 公共的同行庫存, Sumeragi RBC 採樣,節點管理器快照和Connect應用程序註冊表管理都不公開 Taira 在檢查期間使用 request_json("GET", "/status") 對於公共節點狀態有效載荷 Taira.

施工指導

SDK 對最常見的指令家庭的打字構建器和尚未成爲一流 Python 方法的變體的 JSON 逃跑口暴露.下面的摘錄是突變的交易模板,並且沒有在簽署帳戶的情況下提交給公衆 Taira.

當它們存在時,更喜歡打字輔助器:它們將 Python 值正常化並在不有效的形狀上早期失敗.只使用 Instruction.from_json當您需要一個尚未有 Python 輔助器的指示變體時.

教學家庭	Python 表面
登記	`register_account`, `register_asset_definition_numeric`, `register_rwa`, `register_time_trigger`, `register_precommit_trigger`; `register_domain` 專用於創始/啓動鏈工具
取消登記	`unregister_trigger`;使用`Instruction.from_json`用於其他變體
子/燃燒	`mint_asset_numeric`, `burn_asset_numeric`,`mint_trigger_repetitions`, `burn_trigger_repetitions`
轉移	`transfer_asset_numeric`, `transfer_domain`, `transfer_asset_definition`, `transfer_nft`, `transfer_rwa`, `force_transfer_rwa`
大數據和控制	`set_account_key_value`, `remove_account_key_value`, `set_rwa_controls`, `set_rwa_key_value`, `remove_rwa_key_value`
RWA 生命週期	`merge_rwas`, `redeem_rwa`, `freeze_rwa`, `unfreeze_rwa`, `hold_rwa`, `release_rwa`
ExecuteTrigger	`execute_trigger`
補充/定居延長	`repo_initiate`, `repo_unwind`, `repo_margin_call`, `settlement_dvp`, `settlement_pvp`
創業資產鎖定	`open_asset_lock`, `drawdown_asset_lock`,`cancel_asset_lock`, `expire_asset_lock`,加上客戶 `*_and_wait`的助手
補貼/撤銷, SetParameter,日誌,定製,升級以及不常見的註冊/非註冊變體	`Instruction.from_json`或`TransactionBuilder.add_instruction_json`具有法典名稱的 `InstructionBox` JSON

對於保證金類條件付款,見產業資產保證. Python 目前對通用資產鎖定的一流助手曝光;市場和匿名保證人助手不是一流 Python 方法還沒有.

設置域名,然後註冊帳戶和資產

通常的域名創建通過聲明別名規劃器進行,因此 SNS 租合同,所有者功能,報價保護和域名狀態都被檢查在一起.通過您的 SDK 或安裝服務創建一個無祕密的AliasSetupPlanRequestV1意圖,然後使用iroha app alias setup plan和iroha app alias setup apply.不要從應用程序交易中提交Instruction.register_domain;該構建器仍然用於生成/啓動工具.

在域設置計劃提交後,註冊域所有物體.在像 Taira 這樣的共享網絡上,使用分配給你的域名和帳戶命名空間.

python

# The domain and its SNS lease already exist before this transaction.
submit(
    Instruction.register_account(alice, {"display_name": "Alice"}),
    Instruction.register_account(bob, {"display_name": "Bob"}),
    Instruction.register_asset_definition_numeric(
        ROSE_DEFINITION,
        owner=alice,
        scale=2,
        mintable="Infinitely",
        confidential_policy="TransparentOnly",
        metadata={"symbol": "ROS"},
    ),
)

mintable 接受 Infinitely, Once, Not, 或 Limited(n) 已被數據模型接受的值. scale 對於無限制數值資產.

貨幣,燃燒和轉讓資產

這些呼叫使用現有資產 ID. 首先註冊資產定義,然後構建具體的資產 ID 對於擁有資產的賬戶.

python

# Increase the account's asset balance.
submit(Instruction.mint_asset_numeric(ROSE_ASSET, "100.00"))

# Move part of the balance to another account.
submit(Instruction.transfer_asset_numeric(ROSE_ASSET, "25.50", bob))

# Decrease the remaining balance.
submit(Instruction.burn_asset_numeric(ROSE_ASSET, "10.00"))

轉移所有權

轉移所有權變化誰控制域名,資產定義,或 NFT.使用當前的所有者作爲交易權威.

python

# The first argument is the current owner; the last is the new owner.
submit(Instruction.transfer_domain(alice, "wonderland", bob))
submit(Instruction.transfer_asset_definition(alice, ROSE_DEFINITION, bob))
submit(Instruction.transfer_nft(alice, BADGE_NFT, bob))

設置和刪除元數據

基數據值必須是: JSON- 可連續化. TransactionDraft, 在 TransactionConfig 成爲默認目標賬戶.

python

# Values are encoded as JSON metadata under the target account.
submit(
    Instruction.set_account_key_value(
        alice,
        "profile",
        {"display_name": "Alice", "tier": "operator"},
    )
)

# Removing the key deletes the metadata entry from the account.
submit(Instruction.remove_account_key_value(alice, "profile"))

高級助理草案默認的目標是交易權威:

python

draft = TransactionDraft(
    TransactionConfig(chain_id=CHAIN_ID, authority=alice, metadata=TX_METADATA)
)
# With a draft, account metadata methods default to the draft authority.
draft.set_account_key_value("nickname", "Queen Alice")
draft.remove_account_key_value("nickname")

現實資產

RWA 助手使用 JSON-可連續化有效載荷來爲特定資產的元數據,來源和控制者政策. register_rwa不接受id或owner:運行時間產生RwaId,交易權威成爲初始所有者.

python

draft = TransactionDraft(
    TransactionConfig(chain_id=CHAIN_ID, authority=alice, metadata=TX_METADATA)
)

# Register the lot in a domain. Store business identifiers in primary_reference
# or metadata, then query the generated RWA ID after the transaction commits.
draft.register_rwa(
    {
        "domain": "commodities.universal",
        "quantity": "100",
        "spec": {"scale": 0},
        "primary_reference": "warehouse-receipt-001",
        "status": "active",
        "metadata": {
            "commodity": "copper",
            "warehouse": "DXB-01",
        },
        "parents": [],
        "controls": {
            "controller_accounts": [alice],
            "controller_roles": [],
            "freeze_enabled": True,
            "hold_enabled": True,
            "force_transfer_enabled": True,
            "redeem_enabled": True,
        },
    }
)

在註冊交易承諾後,使用 FindRwas, /v1/rwas,RWA 事件或設置的探索者路線來發現生成的 ID:

python

page = client.list_rwas_typed(limit=20, offset=0)

for lot in page.items:
    print(lot.id)

隨後的操作使用生成的 hash$domain ID:

python

registered_rwa_id = (
    "0123456789abcdef0123456789abcdef"
    "0123456789abcdef0123456789abcdef$commodities.universal"
)

draft = TransactionDraft(
    TransactionConfig(chain_id=CHAIN_ID, authority=alice, metadata=TX_METADATA)
)

# Transfer, hold, release, freeze, and redeem model the lot lifecycle.
draft.transfer_rwa(
    registered_rwa_id,
    quantity="10",
    destination=bob,
)
draft.hold_rwa(registered_rwa_id, quantity="5")
draft.release_rwa(registered_rwa_id, quantity="5")
draft.freeze_rwa(registered_rwa_id)
draft.unfreeze_rwa(registered_rwa_id)
draft.redeem_rwa(registered_rwa_id, quantity="1")

# RWA metadata and controls are separate from account metadata.
draft.set_rwa_key_value(registered_rwa_id, "auditor", "alice")
draft.remove_rwa_key_value(registered_rwa_id, "auditor")
draft.set_rwa_controls(
    registered_rwa_id,
    {
        "controller_accounts": [alice],
        "controller_roles": [],
        "freeze_enabled": True,
        "hold_enabled": True,
        "force_transfer_enabled": True,
        "redeem_enabled": True,
    },
)

# Merge consumes quantities from parent lots with the same domain and spec. The
# child lot gets a generated ID.
draft.merge_rwas(
    {
        "parents": [
            {"rwa": registered_rwa_id, "quantity": "40"},
            {
                "rwa": "fedcba9876543210fedcba9876543210"
                "fedcba9876543210fedcba9876543210$commodities.universal",
                "quantity": "60",
            },
        ],
        "primary_reference": "warehouse-receipt-003",
        "status": "merged",
        "metadata": {"merge_reason": "same custodian and quality grade"},
    }
)

# Force transfer requires a configured controller and force_transfer_enabled.
draft.force_transfer_rwa(
    registered_rwa_id,
    quantity="1",
    destination=bob,
)

在現有分數上,全部轉讓可以改變 owned_by.部分轉移和合並會產生子女分數.

觸發器

使用觸發註冊輔助器,當可執行的是另一個指令序列:

python

# The trigger executable is just another instruction payload.
reward = Instruction.mint_asset_numeric(ROSE_ASSET, "1")

# Time triggers run on a schedule once registered.
register_hourly = Instruction.register_time_trigger(
    "hourly_reward",
    alice,
    [reward],
    start_ms=1_800_000_000_000,
    period_ms=3_600_000,
    repeats=24,
    metadata={"purpose": "docs"},
)
submit(register_hourly)

# Precommit triggers run during the transaction pipeline.
register_precommit = Instruction.register_precommit_trigger(
    "precommit_reward",
    alice,
    [reward],
    repeats=10,
    metadata={"purpose": "pipeline test"},
)
submit(register_precommit)

# Trigger execution and repetition changes are also transactions.
submit(Instruction.execute_trigger("hourly_reward", args={"reason": "manual"}))
submit(Instruction.mint_trigger_repetitions("hourly_reward", 5))
submit(Instruction.burn_trigger_repetitions("hourly_reward", 1))
submit(Instruction.unregister_trigger("hourly_reward"))

Torii 還暴露 REST 的助手用於觸發器庫存:

python

# Inventory helpers are reads; they do not unregister or execute triggers.
registered = client.list_triggers_typed(limit=20)
for trigger in registered.items:
    print(trigger.id, trigger.authority)

details = client.get_trigger_typed("precommit_reward")

引發庫存調用只能讀取或檢查引發記錄. 註冊,執行,重複變更和不註冊是突變操作.

申報和結算說明

代理商和雙邊結算助手將無需手工製造的 Norito 有效載荷添加特定領域的指令變體:

python

from iroha_python import (
    RepoCashLeg,
    RepoCollateralLeg,
    RepoGovernance,
    SettlementAtomicity,
    SettlementExecutionOrder,
    SettlementLeg,
    SettlementPlan,
)

config = TransactionConfig(
    chain_id=CHAIN_ID,
    authority=alice,
    # Keep repo and settlement examples bounded by a short TTL.
    ttl_ms=120_000,
    metadata=TX_METADATA,
)
draft = TransactionDraft(config)

# Each repo leg describes one side of the financing agreement.
cash = RepoCashLeg(asset_definition_id="usd#wonderland", quantity="1000")
collateral = RepoCollateralLeg(
    asset_definition_id="bond#wonderland",
    quantity="1050",
    metadata={"isin": "ABC123"},
)
governance = RepoGovernance(haircut_bps=1500, margin_frequency_secs=86_400)

# Domain-specific draft methods append the corresponding instructions.
draft.repo_initiate(
    agreement_id="daily_repo",
    initiator=alice,
    counterparty=bob,
    cash_leg=cash,
    collateral_leg=collateral,
    rate_bps=250,
    maturity_timestamp_ms=1_704_000_000_000,
    governance=governance,
)
draft.repo_margin_call("daily_repo")
draft.repo_unwind(
    agreement_id="daily_repo",
    initiator=alice,
    counterparty=bob,
    cash_leg=cash,
    collateral_leg=collateral,
    settlement_timestamp_ms=1_704_086_400_000,
)

# DVP/PVP settlement plans encode ordering and atomicity for both legs.
delivery = SettlementLeg(
    asset_definition_id="bond#wonderland",
    quantity="10",
    from_account=alice,
    to_account=bob,
    metadata={"isin": "ABC123"},
)
payment = SettlementLeg(
    asset_definition_id="usd#wonderland",
    quantity="1000",
    from_account=bob,
    to_account=alice,
)
plan = SettlementPlan(
    order=SettlementExecutionOrder.PAYMENT_THEN_DELIVERY,
    atomicity=SettlementAtomicity.ALL_OR_NOTHING,
)

draft.settlement_dvp(
    settlement_id="trade_dvp",
    delivery_leg=delivery,
    payment_leg=payment,
    plan=plan,
    metadata={"desk": "rates"},
)
draft.settlement_pvp(
    settlement_id="trade_pvp",
    primary_leg=payment,
    counter_leg=delivery,
)

envelope = draft.sign_with_keypair(alice_pair)
client.submit_transaction_envelope_and_wait(envelope)

JSON 逃跑口

當一個 Python 目前還沒有提供輔助器,供應標準數據模型 InstructionBox JSON 在 Instruction.from_json 或直接進入 TransactionBuilder.add_instruction_json. 這就是推的路徑 Grant, Revoke, SetParameter, Log, Custom, Upgrade, 同類/角色 NFT 在這些輔助器被鍵入之前,非觸發式未登記的變體.

python

from iroha_python import Instruction, TransactionBuilder

# Copy this payload from Rust/CLI tooling or from a pinned data-model schema.
instruction_box_json = """
{
  "<InstructionVariant>": {
    "...": "..."
  }
}
"""

instruction = Instruction.from_json(instruction_box_json)
submit(instruction)

# Use TransactionBuilder when you need lower-level control than TransactionDraft.
builder = TransactionBuilder(CHAIN_ID, alice)
builder.set_metadata(TX_METADATA)
builder.add_instruction_json(instruction_box_json)
envelope = builder.sign(alice_pair.private_key)
client.submit_transaction_envelope_and_wait(envelope)

對於生成或不透明的指示,在存儲燈具之前通過 JSON 進行往返:

python

# Round trips are useful for validating fixtures generated by another tool.
payload = Instruction.mint_asset_numeric(ROSE_ASSET, "1").to_json()
same_instruction = Instruction.from_json(payload)
print(same_instruction.as_dict())

交易工作流程

使用 TransactionDraft用於在簽署之前構建多個指令的應用程序. 草稿允許您將交易級設置,如ttl_ms, nonce和元數據放在一個地方,然後單次簽署:

python

config = TransactionConfig(
    chain_id=CHAIN_ID,
    authority=alice,
    # TTL and nonce are transaction-level properties shared by all instructions.
    ttl_ms=120_000,
    nonce=1,
    metadata={**TX_METADATA, "source": "python-docs"},
)

draft = TransactionDraft(config)
# Draft methods append instructions but do not submit anything yet. Domain
# setup is a separate alias-planner flow and has already committed here.
draft.register_account(bob, metadata={"role": "user"})
draft.register_asset_definition_numeric(
    ROSE_DEFINITION,
    owner=alice,
    scale=2,
    mintable="Infinitely",
)
draft.mint_asset_numeric(ROSE_ASSET, "100")
draft.transfer_asset_numeric(ROSE_ASSET, "25", destination=bob)

# Signing freezes the draft into an envelope ready for Torii.
envelope = draft.sign_with_keypair(alice_pair)
receipt = client.submit_transaction_envelope(envelope)
status = client.wait_for_transaction_status(envelope.hash_hex(), timeout=30)
print(receipt, status)

出口檢查,審計或錢包轉移的確定性表格:

python

import json
from pathlib import Path

# Manifests are review artifacts; they are not submitted by themselves.
manifest = draft.to_manifest_dict(include_creation_time=True)
print(json.dumps(manifest, indent=2))

Path("transaction_manifest.json").write_text(
    draft.to_manifest_json(indent=2, include_creation_time=True),
    encoding="utf-8",
)

當目標車道要求時,在簽署前附上一個路徑隱私證明:

python

# Attach the proof before signing so it is covered by the transaction hash.
draft.add_lane_privacy_merkle_proof(
    commitment_id=7,
    leaf=bytes.fromhex("aa" * 32),
    leaf_index=3,
    audit_path=[bytes.fromhex("bb" * 32), None, bytes.fromhex("cc" * 32)],
    proof_backend="halo2/ipa",
    proof_bytes=b"...proof bytes...",
    verifying_key_bytes=b"...verifying key bytes...",
)
envelope = draft.sign_with_keypair(alice_pair)

問題

輸入查詢輔助器返回數據類,而不是原始的 JSON 字典.它們是最簡單的方式來開始,因爲 SDK 解析頁面化和常見記錄領域:

python

# Typed pages expose `.items` plus pagination metadata such as `.total`.
accounts = client.list_accounts_typed(limit=25, sort="id")
for account in accounts.items:
    print(account.id, account.metadata)

domains = client.list_domains_typed(limit=10)
definitions = client.query_asset_definitions_typed(limit=10)
print(domains.total, definitions.total)

在 Torii 終端點尚未有打字包裝時,使用通用請求輔助器:

python

# Drop to raw JSON when you need an endpoint before a typed helper exists.
payload = client.request_json("GET", "/v1/parameters", expected_status=(200,))
metrics = client.get_metrics(as_text=True)

賬戶庫存輔助者需要一個由 SDK 是正常化器,使用法典. I105 賬戶 IDs 如果一個區塊探測器或原始終點返回一個 ID 這就是 SDK 拒絕,將其歸結爲法典賬號 ID 在召喚這些援助者之前,

python

# These helpers expect a canonical account ID or an alias the SDK can normalize.
assets = client.list_account_assets_typed(alice, limit=10)
transactions = client.query_account_transactions_typed(alice, limit=5)
permissions = client.list_account_permissions_typed(alice, limit=20)

print(len(assets.items), len(transactions.items), len(permissions.items))

事件

流媒體輔助器默認地解碼 JSON 有效載荷. 當您需要 SSE 事件名稱,ID,重試提示和原始有效載荷時,請通過with_metadata=True .EventCursor將最新事件ID保持.這些例子等待現場事件,所以運行它們與相應的事件流啓用和激活的節點.

python

from iroha_python import DataEventFilter, EventCursor

# Narrow the stream to proof events with the expected backend and proof hash.
proof_filter = DataEventFilter.proof(
    backend="halo2/ipa",
    proof_hash_hex="deadbeef" * 8,
)

# Persist the latest SSE id so a reconnect can resume from the same point.
cursor = EventCursor()
for event in client.stream_events(
    filter=proof_filter,
    cursor=cursor,
    resume=True,
    with_metadata=True,
):
    print(event.id, event.event, event.data)
    break

for event in client.stream_trigger_events(trigger_id="hourly_reward", resume=True):
    print(event)
    break

for tx_event in client.stream_pipeline_transactions(status="Queued"):
    print(tx_event)
    break

鑰匙和地址

SDK 暴露在本地擴展中編譯的每個簽名算法的本地簽字輔助器.這些輔助器不調用 Taira,但它們確實需要本地擴充:

python

from iroha_python import (
    ED25519_ALGORITHM,
    derive_confidential_keyset_from_hex,
    derive_keypair_from_seed,
    hash_blake2b_32,
    verify,
)
from iroha_python.address import AccountAddress

# Key derivation and signing are local; no network call is made here.
ed_pair = derive_keypair_from_seed(b"alice", ED25519_ALGORITHM)
signature = ed_pair.sign(b"payload")
assert verify(ED25519_ALGORITHM, ed_pair.public_key, b"payload", signature)

# Canonical AccountId/I105 identity is derived only from the controller key.
# This constructor currently requires `domain`; canonical identity ignores it
# and AccountAddress.from_account emits a domainless address.
address = AccountAddress.from_account(domain="wonderland", public_key=ed_pair.public_key)
print(address.canonical_hex())
print(address.to_i105(0x02F1))

# Confidential key helpers derive local viewing/spending material.
confidential = derive_confidential_keyset_from_hex("01" * 32)
print(confidential.as_hex())
print(hash_blake2b_32(b"payload").hex())

使用 supported_crypto_algorithms() 查看您的輪子支持什麼.通用輔助器使用法定算法的標籤,並在這些算法編譯時工作 Ed25519, secp256k1, ML-DSA,GOST, BLS 和 SM2:

python

from iroha_python import (
    CryptoKeyPair,
    derive_keypair_from_seed,
    load_keypair,
    parse_private_key_multihash,
    parse_public_key_multihash,
    private_key_multihash,
    public_key_multihash,
    sign,
    supported_crypto_algorithms,
    verify,
)

message = b"iroha multi-algorithm signing"

# Iterate the algorithms compiled into the installed native extension.
for algorithm in supported_crypto_algorithms():
    keypair = derive_keypair_from_seed(f"docs:{algorithm}".encode(), algorithm)
    signature = keypair.sign(message)

    # Both the object method and the generic helper verify the same signature.
    assert keypair.verify(message, signature)
    assert verify(algorithm, keypair.public_key, message, signature)

    # Loading a private key should reconstruct the same public key.
    loaded = load_keypair(keypair.private_key, algorithm)
    assert loaded.public_key == keypair.public_key
    assert sign(algorithm, loaded.private_key, message) != b""

    # Prefixed multihashes carry the algorithm label with the key bytes.
    public_multihash = public_key_multihash(
        algorithm,
        keypair.public_key,
        prefixed=True,
    )
    private_multihash = private_key_multihash(
        algorithm,
        keypair.private_key,
        prefixed=True,
    )

    public_algorithm, public_key = parse_public_key_multihash(public_multihash)
    private_algorithm, private_key = parse_private_key_multihash(private_multihash)
    restored = CryptoKeyPair.from_private_key_multihash(private_multihash)

    # Round-trip checks catch mismatched algorithm labels or key encodings.
    assert public_algorithm == algorithm
    assert public_key == keypair.public_key
    assert private_algorithm == algorithm
    assert private_key == keypair.private_key
    assert restored == keypair

中文 SM 加密

Python SDK 將通用 SM2 輔助器和特定 SM2 的便利輔助器都曝光.使用節點能力廣告來選擇目標網絡預期的 SM2 區分標識符:

python

from iroha_python import (
    SM2_ALGORITHM,
    SM2_DEFAULT_DISTINGUISHED_ID,
    derive_keypair_from_seed,
    derive_sm2_keypair_from_seed,
    sign,
    sign_sm2,
    verify,
    verify_sm2,
)

capabilities = client.get_node_capabilities_typed()
sm = capabilities.crypto.sm if capabilities.crypto else None
# Use the node's default SM2 distinguishing ID when the node advertises one.
distid = sm.sm2_distid_default if sm else SM2_DEFAULT_DISTINGUISHED_ID

# The SM2-specific helper accepts the distinguishing ID explicitly.
pair = derive_sm2_keypair_from_seed(bytes.fromhex("11" * 32), distid=distid)
message = b"iroha-sm2-example"
signature = pair.sign(message)

assert pair.verify(message, signature)
assert verify_sm2(pair.public_key, message, signature, distid=distid)
assert sign_sm2(pair.private_key, message, distid=distid) != b""

# The generic API works when you only need the canonical `sm2` label.
generic_pair = derive_keypair_from_seed(bytes.fromhex("22" * 32), SM2_ALGORITHM)
generic_signature = sign(SM2_ALGORITHM, generic_pair.private_key, message)
assert verify(SM2_ALGORITHM, generic_pair.public_key, message, generic_signature)

print(pair.public_key_sec1_hex)
print(pair.public_key_multihash)

crypto.sm.enabled告訴您節點是否在當前的政策中接受 SM 家族算法.同樣的廣告包括 SM 哈希政策和加速狀態,這對於決定是否啓用 SM2 特定流程時有用:

python

capabilities = client.get_node_capabilities_typed()

# `enabled` is the submit-time policy flag, not just local SDK support.
if capabilities.crypto and capabilities.crypto.sm.enabled:
    sm = capabilities.crypto.sm
    print(sm.default_hash)
    print(sm.allowed_signing)
    print(sm.acceleration.policy)
else:
    print("SM crypto is not enabled by this node")

在檢查期間,公衆 Taira 曝光了 SM 功能廣告,但在那裏被禁用 SM 簽名.其廣告的簽名算法是ed25519,secp256k1和bls_normal,因此,除非能力有效載荷發生變化,否則不要向 SM2 簽署的交易提交該部署.

GOST 和數量後關鍵

在 GOST R 34.10-2012 參數組和 ML-DSA (ml-dsa) 後量子簽名中,使用通用加密字符號 API.同一個鍵對對處理簽名,驗證和多哈希出口:

python

from iroha_python import (
    GOST_3410_2012_256_PARAMSET_A_ALGORITHM,
    GOST_3410_2012_256_PARAMSET_B_ALGORITHM,
    GOST_3410_2012_256_PARAMSET_C_ALGORITHM,
    GOST_3410_2012_512_PARAMSET_A_ALGORITHM,
    GOST_3410_2012_512_PARAMSET_B_ALGORITHM,
    ML_DSA_ALGORITHM,
    derive_keypair_from_seed,
    verify,
)
from iroha_python.address import AccountAddress

CHAIN_DISCRIMINANT = 0x02F1
message = b"iroha gost and post-quantum example"

# Crypto helpers use canonical labels; account addresses use compact aliases.
# Every `domain=` argument below is ignored when the canonical AccountId/I105
# address is encoded.
GOST_ADDRESS_ALIASES = {
    GOST_3410_2012_256_PARAMSET_A_ALGORITHM: "gost-256-a",
    GOST_3410_2012_256_PARAMSET_B_ALGORITHM: "gost-256-b",
    GOST_3410_2012_256_PARAMSET_C_ALGORITHM: "gost-256-c",
    GOST_3410_2012_512_PARAMSET_A_ALGORITHM: "gost-512-a",
    GOST_3410_2012_512_PARAMSET_B_ALGORITHM: "gost-512-b",
}

# Derive and verify one local keypair for every GOST parameter set.
for crypto_algorithm, address_algorithm in GOST_ADDRESS_ALIASES.items():
    keypair = derive_keypair_from_seed(
        f"docs:{crypto_algorithm}".encode(),
        crypto_algorithm,
    )
    signature = keypair.sign(message)

    assert verify(crypto_algorithm, keypair.public_key, message, signature)

    address = AccountAddress.from_account(
        domain="wonderland",
        public_key=keypair.public_key,
        # Account addresses use compact curve aliases for GOST parameter sets.
        algorithm=address_algorithm,
    )
    print(crypto_algorithm)
    print(address.canonical_hex())
    print(address.to_i105(CHAIN_DISCRIMINANT))
    print(keypair.prefixed_public_key_multihash)

# ML-DSA follows the same generic signing and address flow.
mldsa_keypair = derive_keypair_from_seed(b"docs:ml-dsa", ML_DSA_ALGORITHM)
mldsa_signature = mldsa_keypair.sign(message)
assert verify(ML_DSA_ALGORITHM, mldsa_keypair.public_key, message, mldsa_signature)
post_quantum_address = AccountAddress.from_account(
    domain="wonderland",
    public_key=mldsa_keypair.public_key,
    algorithm="ml-dsa",
)
print(post_quantum_address.canonical_hex())
print(post_quantum_address.to_i105(CHAIN_DISCRIMINANT))
print(mldsa_keypair.prefixed_public_key_multihash)

在節點的廣告簽名算法上,Gate GOST 和後量子流量.使用原始功能有效載荷來預先兼容算法的名稱:

python

capabilities = client.request_json(
    "GET",
    "/v1/node/capabilities",
    expected_status=(200,),
)
crypto = capabilities.get("crypto", {})
sm = crypto.get("sm", {})
# Nodes advertise the signing algorithms they will accept for transactions.
allowed = set(sm.get("allowed_signing", []))

GOST_ALGORITHMS = {
    "gost3410-2012-256-paramset-a",
    "gost3410-2012-256-paramset-b",
    "gost3410-2012-256-paramset-c",
    "gost3410-2012-512-paramset-a",
    "gost3410-2012-512-paramset-b",
}

# Local support is not enough; submit only when the node advertises support.
supports_gost = bool(allowed & GOST_ALGORITHMS)
supports_post_quantum = "ml-dsa" in allowed
supports_sm2 = "sm2" in allowed and bool(sm.get("enabled", False))

print(supports_gost, supports_post_quantum, supports_sm2)

如果一個節點不廣告您所需的算法,請僅用於本地或離線工作流程.不要向該節點提交與該算法的簽名交易.在公共 Taira 檢查期間, GOST 和 ML-DSA 在上游 Python 圖書館中作爲 SDK 加密助手可用,但並沒有被節點用於簽署交易的廣告.

設置知情客戶端創建

使用 resolve_torii_client_config 當您的應用程序從文件中讀取節點設置,但仍然需要環境或測試特定的過關:

python

import json
from iroha_python import create_torii_client, resolve_torii_client_config

with open("iroha_config.json", "r", encoding="utf-8") as handle:
    raw_config = json.load(handle)

# Override only the fields that vary by environment.
resolved = resolve_torii_client_config(
    config=raw_config,
    overrides={"timeout_ms": 2_000, "max_retries": 5},
)

# Pass the resolved config into the same client constructor used elsewhere.
client = create_torii_client(
    raw_config.get("torii", {}).get("address", TORII_URL),
    resolved_config=resolved,
)

卡蓋穆沙的準備

其他 Python SDK 能查詢電流 JSON 準備路線通過其通用 Torii 要求助理:

python

ASSET_DEFINITION_ID = "<canonical_asset_definition_id>"

readiness = client.request_json(
    "GET",
    "/v1/offline/readiness",
    params={"asset_definition_id": ASSET_DEFINITION_ID},
    headers={"Accept": "application/json"},
    expected_status=(200,),
)
print(readiness["ready"])
print(readiness["blockers"])

Python 沒有曝光打字的 Kagemusha補充或贖回檔案構建器. Swift 或 JVM 爲了構建神聖的錢包 V4 然後通過支持的 Kagemusha 提交併進行調查. Torii 客戶.

# The plan defines billing cadence, retry policy, and usage pricing.
usage_plan = {
    "provider": alice,
    "billing": {
        "cadence": {
            "kind": "monthly_calendar",
            "detail": {"anchor_day": 1, "anchor_time_ms": 0},
        },
        "bill_for": {"period": "previous_period", "value": None},
        "retry_backoff_ms": 86_400_000,
        "max_failures": 3,
        "grace_ms": 604_800_000,
    },
    "pricing": {
        "kind": "usage",
        "detail": {
            "unit_price": "0.024",
            "unit_key": "compute_ms",
            "asset_definition": "usd#wonderland",
        },
    },
}

# The provider signs plan creation.
client.create_subscription_plan(
    authority=alice,
    private_key=alice_pair.private_key_hex,
    plan_id="compute#wonderland",
    plan=usage_plan,
)

# The subscriber signs subscription creation.
client.create_subscription(
    authority=bob,
    private_key=bob_pair.private_key_hex,
    subscription_id="sub-001",
    plan_id="compute#wonderland",
)

# Usage is recorded by the provider and then charged on demand.
client.record_subscription_usage(
    "sub-001",
    authority=alice,
    private_key=alice_pair.private_key_hex,
    unit_key="compute_ms",
    delta="3600000",
)
client.charge_subscription_now(
    "sub-001",
    authority=alice,
    private_key=alice_pair.private_key_hex,
)

連接

建立和分析連接 URIs,並閱讀由 Taira 暴露的公共連接狀態:

python

from iroha_python.connect import ConnectUri, build_connect_uri, parse_connect_uri

# Connect URIs are what an app hands to a wallet to start a session.
uri = build_connect_uri(
    ConnectUri(
        sid="base64url-session-id",
        chain_id=CHAIN_ID,
        node="taira.sora.org",
    )
)
parsed = parse_connect_uri(uri)
# Status tells you whether the node currently exposes Connect.
status = client.get_connect_status_typed()

assert parsed.chain_id == CHAIN_ID
print(status.enabled, status.sessions_active)

框架代碼,會話鍵衍生和會話創建需要本地擴展和啓用Connect會話路線:

python

from iroha_python import (
    ConnectControlClose,
    ConnectControlOpen,
    ConnectDirection,
    ConnectFrame,
    ConnectPermissions,
    decode_connect_frame,
    encode_connect_frame,
    generate_connect_keypair,
)

# The app keypair is separate from the account key used for transactions.
connect_pair = generate_connect_keypair()
info = client.create_connect_session_info(
    {"role": "app", "sid": connect_pair.public_key.hex()}
)
print(info.app_uri, info.wallet_token, info.expires_at)

# Control frames negotiate permissions before encrypted messages are sent.
frame = ConnectFrame(
    sid=bytes.fromhex("01" * 32),
    direction=ConnectDirection.APP_TO_WALLET,
    sequence=1,
    control=ConnectControlOpen(
        app_public_key=connect_pair.public_key,
        chain_id=CHAIN_ID,
        permissions=ConnectPermissions(methods=["SIGN_REQUEST_TX"], events=[]),
    ),
)
payload = encode_connect_frame(frame)
assert decode_connect_frame(payload) == frame

# Closing the control channel is explicit and carries a reason code.
client.send_connect_control_frame(
    "base64url-session-id",
    ConnectControlClose(role="App", code=4100, reason="finished", retryable=False),
)

通過狀態會議加密後的消息:

python

from iroha_python import (
    ConnectDirection,
    ConnectSession,
    ConnectSessionKeys,
    ConnectSignRequestRawPayload,
)

# Derive symmetric session keys from both parties' keys and the session ID.
keys = ConnectSessionKeys.derive(
    local_private_key=bytes.fromhex("11" * 32),
    peer_public_key=bytes.fromhex("22" * 32),
    sid=bytes.fromhex("33" * 32),
)
session = ConnectSession(
    sid=bytes.fromhex("33" * 32),
    keys=keys,
)
# Encrypt application payloads after the session is approved.
encrypted = session.encrypt_app_to_wallet(
    ConnectSignRequestRawPayload(domain_tag="SIGN", payload=b"hash")
)
state = session.snapshot_state().to_dict()
print(encrypted.sequence, state)

管理,運行時間和管理面積

這些只可讀的電話成功回覆了公衆 Taira:

python

client = create_torii_client("https://taira.sora.org")

# Governance reads return either current settings or typed not-found wrappers.
protected = client.get_protected_namespaces()
referendum = client.get_governance_referendum_typed("ref-1")
tally = client.get_governance_tally_typed("ref-1")
locks = client.get_governance_locks_typed("ref-1")
unlock_stats = client.get_governance_unlock_stats_typed()

print(protected, referendum.found)
print(tally.approve, list(locks.locks), unlock_stats.expired_locks_now)

# Runtime reads expose the active ABI and any pending upgrade records.
abi = client.get_runtime_abi_active_typed()
abi_hash = client.get_runtime_abi_hash_typed()
runtime_metrics = client.get_runtime_metrics_typed()
upgrades = client.list_runtime_upgrades_typed()
capabilities = client.get_node_capabilities_typed()

print(abi, abi_hash, runtime_metrics)
print(upgrades.total, capabilities.abi_version)

運行時間升級輔助器接受運行時升級 API 所使用的表格形狀.它們是操作員操作,因此只應對帳戶和代幣授權的節點進行使用:

python

admin = create_torii_client(
    TORII_URL,
    auth_token="admin-token",
api_token="torii-token",
)

# Propose creates the upgrade instructions; activation/cancel are operator actions.
upgrade = admin.propose_runtime_upgrade(
    {
        "name": "Refresh runtime provenance",
        "description": "Schedules a no-ABI-change runtime rollout.",
        "abi_version": 1,
        "abi_hash": "00" * 32,
        "added_syscalls": [],
        "added_pointer_types": [],
        "start_height": 1_500_000,
        "end_height": 1_500_256,
    }
)
print(upgrade["tx_instructions"])

admin.activate_runtime_upgrade("deadbeef" * 4)
admin.cancel_runtime_upgrade("feedface" * 4)

狀態,共識和網絡電測

python

# `/status` is the public node snapshot endpoint on Taira.
status = client.request_json("GET", "/status", expected_status=(200,))
print(status["blocks"], status["txs_approved"])

# Sumeragi and time endpoints expose consensus and clock diagnostics.
sumeragi = client.get_sumeragi_status_typed()
print(sumeragi.highest_qc.height, sumeragi.tx_queue.saturated)

time_now = client.get_time_now_typed()
time_status = client.get_time_status_typed()
for sample in time_status.samples:
    print(sample.peer, sample.last_offset_ms, sample.last_rtt_ms)
print(time_now.now_ms)

SoraFS,UAID 和 Kaigi 的輔助人員

當目標節點暴露相應的 Nexus/SORA 終端點時,這些輔助器可用.將空清單視爲有效的響應:公衆 Taira 可能會在沒有樣本表或 UAID 的數據的情況下啓用路線.

python

# SoraFS status queries are reads scoped by manifest and status.
por_status = client.get_sorafs_por_status(manifest_hex="ab" * 32, status="verified")
print(len(por_status))

# UAID helpers inspect wallet/data-space bindings for one identifier.
uaid = "aabb" * 16
bindings = client.get_uaid_bindings_typed(uaid)
manifests = client.list_space_directory_manifests_typed(
    uaid,
    dataspace=11,
    status="active",
)
print(len(bindings.dataspaces), len(manifests.manifests))

# Kaigi health summarizes relay availability when the route is enabled.
health = client.get_kaigi_relays_health_typed()
print(health.healthy_total, health.failovers_total)

Norito RPC 和 GPU 助手

使用 NoritoRpcClient 當你已經有了 Norito 字節和需要調用二進制 Torii 結尾點:該示例需要從前一個交易模板中籤署的包裹:

python

from iroha_python import NoritoRpcClient, NoritoRpcConfig

# Use the binary RPC client for endpoints that expect Norito bytes.
with NoritoRpcClient(NoritoRpcConfig(TORII_URL, timeout=5.0)) as rpc:
    response_bytes = rpc.call("/v1/transaction", envelope.signed_transaction_versioned)
    print(len(response_bytes))

CUDA 輔助器在後端不提供時返回None,因此應用程序可以回到規模實現:

python

from iroha_python import bn254_add_cuda, cuda_available, poseidon2_cuda

# Always probe CUDA availability before calling optional GPU helpers.
if cuda_available():
    print(poseidon2_cuda(1, 2))
    print(bn254_add_cuda((1, 0, 0, 0), (2, 0, 0, 0)))

目前覆蓋範圍

Python SDK 已經包括以下類型的助手:

Torii 提交,狀態,查詢和管理流
爲常見 ISI 和特定域的擴展類型指令構建器
交易草案,宣言,簽署和簽署的交易包裹工作流程
流媒體事件,過器和可重新啓動的線索
一般Kagemusha準備訪問和 Torii 訂閱輔助員;打字補充和贖回構建者不暴露
賬戶地址,全算法簽字輔助器,多個哈希回來旅行, SM2, GOST, ML-DSA, BLS 以及機密鑰處理
連接 URIs,會議,框架,加密輔助器和註冊表管理員
管理,運行時間升級, Sumeragi,節點-admin, SoraFS,UAID 和 Kaigi 的終端點包裝,其中節點暴露了這些特性

上游引用

python/iroha_python/README.md
python/iroha_python/DESIGN.md
python/iroha_python/src/iroha_python

這些文件是嵌入式工作空間修改中 Python 表面的真相來源.

Python ​

安裝 ​

快速開始 ​

分享的設置 ​

費用和天然氣 ​

Taira - 檢查的僅閱讀通話 ​

施工指導 ​

設置域名,然後註冊帳戶和資產 ​

貨幣,燃燒和轉讓資產 ​

轉移所有權 ​

設置和刪除元數據 ​

現實資產 ​

觸發器 ​

申報和結算說明 ​

JSON 逃跑口 ​

交易工作流程 ​

問題 ​

事件 ​

鑰匙和地址 ​

中文 SM 加密 ​

GOST 和數量後關鍵 ​

設置知情客戶端創建 ​

卡蓋穆沙的準備 ​

訂閱 ​

連接 ​

管理,運行時間和管理面積 ​

狀態,共識和網絡電測 ​

SoraFS,UAID 和 Kaigi 的輔助人員 ​

Norito RPC 和 GPU 助手 ​

目前覆蓋範圍 ​

上游引用 ​

Python

安裝

快速開始

分享的設置

費用和天然氣

Taira - 檢查的僅閱讀通話

施工指導

設置域名,然後註冊帳戶和資產

貨幣,燃燒和轉讓資產

轉移所有權

設置和刪除元數據

現實資產

觸發器

申報和結算說明

JSON 逃跑口

交易工作流程

問題

事件

鑰匙和地址

中文 SM 加密

GOST 和數量後關鍵

設置知情客戶端創建

卡蓋穆沙的準備

訂閱

連接

管理,運行時間和管理面積

狀態,共識和網絡電測

SoraFS,UAID 和 Kaigi 的輔助人員

Norito RPC 和 GPU 助手

目前覆蓋範圍

上游引用