API reference ¶

async submit_nowait(call, keypair, *, tip=0, era_period=64, validate=True)[source]¶

Sign and send without waiting for a block; returns the extrinsic hash.

Parameters:

call (Call)
keypair (Keypair)
tip (int)
era_period (int | None)
validate (bool)

Return type:

class robonomicsinterface.RobonomicsSync(endpoints='wss://polkadot.rpc.robonomics.network/', **options)[source]¶

The blocking counterpart of RobonomicsClient; same arguments.

Parameters:

endpoints (str | Sequence[str])
options (Any)

property client: RobonomicsClient¶: The underlying async client (for use from its own loop only).

close()[source]¶

Close the connection and stop the background thread.

Return type:: None

query_map(pallet, item, *keys, at=None, page_size=100)[source]¶

Iterate over a storage map; pages are fetched as the iteration goes.

Parameters:

pallet (str)
item (str)
keys (Any)
at (str | None)
page_size (int)

Return type:

Iterator[tuple[tuple[Any, …], Any]]

Pallets¶

Datalog: a per-account ring buffer of timestamped records.

Each account has WindowSize (128) slots. DatalogIndex holds start and end: live records are at start, start+1, …, end-1 modulo the window, oldest first. When the buffer is full, start moves on, so at most WindowSize - 1 records are live; the slot at end may still hold an overwritten record and is not one of them.

class robonomicsinterface.pallets.datalog.Datalog(client)[source]¶

client.datalog: read and write datalog records.

Parameters:: client (RobonomicsClient)

async index(address, *, at=None)[source]¶

The ring buffer bounds of address.

Parameters:

address (str | Keypair)
at (str | None)

Return type:

DatalogIndex

async item(address, index, *, at=None)[source]¶

The record in slot index — 0 means slot 0 — or None if the slot holds no live record.

Parameters:

address (str | Keypair)
index (int)
at (str | None)

Return type:

DatalogItem | None

async latest(address, *, at=None)[source]¶

The newest record, or None if there are none.

Parameters:

address (str | Keypair)
at (str | None)

Return type:

DatalogItem | None

async items(address, *, at=None)[source]¶

All live records, oldest first, read in one request.

Parameters:

address (str | Keypair)
at (str | None)

Return type:

list[DatalogItem]

async record(keypair, data, *, subscription_owner=None, **options)[source]¶

Write a record (at most 512 bytes; str is sent as UTF-8).

Parameters:

subscription_owner (str | None) – publish through this RWS subscription (RWS.call, free of fees) instead of paying.
keypair (Keypair)
data (bytes | str)
options (Unpack[SubmitOptions])

Return type:

async erase(keypair, *, subscription_owner=None, **options)[source]¶

Remove all records of the signer.

Parameters:

keypair (Keypair)
subscription_owner (str | None)
options (Unpack[SubmitOptions])

Return type:

class robonomicsinterface.pallets.datalog.DatalogIndex(start: 'int', end: 'int', window_size: 'int')[source]¶

Parameters:

start (int)
end (int)
window_size (int)

property count: int¶: How many records are live.

property positions: list[int]¶: Slot numbers of the live records, oldest first.

class robonomicsinterface.pallets.datalog.DatalogItem(index, timestamp_ms, data)[source]¶

One record: its slot, when it was written, and its bytes.

Parameters:

index (int)
timestamp_ms (int)
data (bytes)

property text: str | None¶: The record as UTF-8 text, or None if it is not valid UTF-8.

RWS: Robonomics Web Services subscriptions.

A subscription owner lists up to MaxDevicesAmount (32) device accounts; each device can then send calls through RWS.call free of fees, paid from the subscription’s accrued free weight. A daily subscription that has expired stays on chain but stops accruing, so calls start failing with FreeWeightIsNotEnough rather than NoSubscription.

class robonomicsinterface.pallets.rws.RWS(client)[source]¶

client.rws: subscriptions, their devices and free calls.

Parameters:: client (RobonomicsClient)

async ledger(owner, *, at=None)[source]¶

The subscription of owner, or None if it has none.

Parameters:

owner (str | Keypair)
at (str | None)

Return type:

Ledger | None

async devices(owner, *, at=None)[source]¶

The devices allowed to use owner’s subscription.

Parameters:

owner (str | Keypair)
at (str | None)

Return type:

list[str]

async set_devices(owner, devices, **options)[source]¶

Replace the whole device list of owner’s subscription.

Addresses are checked and normalised, duplicates dropped (order kept). An empty list removes every device.

Raises:

TooManyDevices – more than MaxDevicesAmount devices.

Parameters:

owner (Keypair)
devices (Iterable[str | Keypair])
options (Unpack[SubmitOptions])

Return type:

async add_devices(owner, *devices, **options)[source]¶

Add devices to the list: read it, extend it, write it back.

Returns None if every device is already listed. Not atomic: two concurrent edits of one owner’s list can lose one of them.

Parameters:

owner (Keypair)
devices (str | Keypair)
options (Unpack[SubmitOptions])

Return type:

ExtrinsicResult | None

async remove_devices(owner, *devices, **options)[source]¶

Remove devices from the list; None if none of them was listed.

Parameters:

owner (Keypair)
devices (str | Keypair)
options (Unpack[SubmitOptions])

Return type:

ExtrinsicResult | None

async call(device, owner, call, **options)[source]¶

Send call as device, paid by owner’s subscription.

Parameters:

device (Keypair)
owner (str | Keypair)
call (Call)
options (Unpack[SubmitOptions])

Return type:

async bid(bidder, index, amount, **options)[source]¶

Bid amount (in the smallest unit, 10⁻⁹ XRT) in auction index.

Parameters:

bidder (Keypair)
index (int)
amount (int)
options (Unpack[SubmitOptions])

Return type:

class robonomicsinterface.pallets.rws.Ledger(kind, days, tps, issue_time_ms, last_update_ms, free_weight)[source]¶

A subscription, as RWS.Ledger stores it.

Parameters:

kind (str)
days (int | None)
tps (int | None)
issue_time_ms (int)
last_update_ms (int)
free_weight (int)

property expires_at: datetime | None¶: When a daily subscription stops accruing; None for a lifetime one.

days_left(now_ms=None)[source]¶

Days until expiry (0 when expired); None for a lifetime subscription.

Parameters:: now_ms (int | None)
Return type:: float | None

exception robonomicsinterface.pallets.rws.TooManyDevices[source]¶: The device list would exceed the runtime’s MaxDevicesAmount.

Accounts, balances and blocks.

class robonomicsinterface.pallets.system.AccountInfo(nonce, consumers, providers, sufficients, free, reserved, frozen)[source]¶

System.Account: nonce, references and balance (in 10⁻⁹ XRT).

Parameters:

nonce (int)
consumers (int)
providers (int)
sufficients (int)
free (int)
reserved (int)
frozen (int)

property exists: bool¶

Whether the account exists on chain, i.e. can sign transactions.

An account with nothing providing for it (no balance above the existential deposit) is absent: its transactions fail with InvalidTransaction::Payment, even free RWS calls.

class robonomicsinterface.pallets.system.Balances(client)[source]¶

client.balances: XRT transfers.

Parameters:: client (RobonomicsClient)

async existential_deposit(*, at=None)[source]¶

The minimum balance for an account to exist (in 10⁻⁹ XRT).

Parameters:: at (str | None)
Return type:: int

async transfer_keep_alive(sender, destination, amount, **options)[source]¶

Send amount (10⁻⁹ XRT); refused if it would leave the sender below the existential deposit.

Parameters:

sender (Keypair)
destination (str | Keypair)
amount (int)
options (Unpack[SubmitOptions])

Return type:

async transfer_allow_death(sender, destination, amount, **options)[source]¶

Send amount (10⁻⁹ XRT), even if the sender’s account is then reaped.

Parameters:

sender (Keypair)
destination (str | Keypair)
amount (int)
options (Unpack[SubmitOptions])

Return type:

class robonomicsinterface.pallets.system.Chain(client)[source]¶

client.chain: blocks and the runtime version.

Parameters:: client (RobonomicsClient)

async block_number(block_hash=None)[source]¶

The number of block_hash, or of the best block.

Parameters:: block_hash (str | None)
Return type:: int

class robonomicsinterface.pallets.system.System(client)[source]¶

client.system: accounts.

Parameters:: client (RobonomicsClient)

async next_nonce(address)[source]¶

The nonce for the account’s next transaction, counting the pool.

Parameters:: address (str | Keypair)
Return type:: int

class robonomicsinterface.pallets.SubmitOptions[source]¶: Options passed through to RobonomicsClient.submit().

Extrinsics¶

Calls, signed extrinsics, and what the chain says about them afterwards.

Everything here is offline: it takes a Runtime and produces bytes, or takes bytes from the chain and explains them. The client does the talking.

Signed extensions are read from the runtime metadata, in its order. Each one contributes an explicit part (sent in the extrinsic) and an implicit part (only signed); the values come from EXTENSION_VALUES. An extension this library does not know is fine if both its parts are empty, and an UnsupportedExtension otherwise — never a silently wrong signature.

class robonomicsinterface.extrinsic.Call(pallet, function, args, data, scale_value, spec_version=0)[source]¶

An encoded call, ready to sign or to nest (RWS.call, Utility.batch).

Parameters:

pallet (str)
function (str)
args (Mapping[str, Any])
data (bytes)
scale_value (dict[str, Any])
spec_version (int)

class robonomicsinterface.extrinsic.Era(period=None, phase=0)[source]¶

How long a signed extrinsic stays valid.

An immortal extrinsic is valid until its nonce is used. A mortal one is valid for period blocks from the block it names, so a lost or stuck transaction cannot land much later — and cannot be replayed if the account is ever reaped and its nonce starts again from zero.

Parameters:

period (int | None)
phase (int)

classmethod mortal(period, current_block)[source]¶

Valid for about period blocks (rounded to a power of two, 4..65536).

Parameters:

period (int)
current_block (int)

Return type:

Era

birth(current_block)[source]¶

The block whose hash the extrinsic commits to.

Parameters:: current_block (int)
Return type:: int

class robonomicsinterface.extrinsic.Event(pallet, name, attributes, extrinsic_index)[source]¶

One runtime event, e.g. Event("Datalog", "NewRecord", (...)).

Parameters:

pallet (str)
name (str)
attributes (Any)
extrinsic_index (int | None)

class robonomicsinterface.extrinsic.ExtrinsicResult(extrinsic_hash, block_hash, block_number, index, events, finalized)[source]¶

An extrinsic that made it into a block, and the events it produced.

Parameters:

extrinsic_hash (str)
block_hash (str)
block_number (int)
index (int)
events (tuple[Event, ...])
finalized (bool)

find(pallet, name)[source]¶

The first event pallet.name of this extrinsic, if any.

Parameters:

pallet (str)
name (str)

Return type:

Event | None

class robonomicsinterface.extrinsic.SignedExtrinsic(data, hash, call, signer, nonce, era)[source]¶

A signed extrinsic, ready for author_submitExtrinsic.

Parameters:

data (bytes)
hash (str)
call (Call)
signer (str)
nonce (int)
era (Era)

class robonomicsinterface.extrinsic.SigningContext(nonce, era, birth_hash, genesis_hash, spec_version, transaction_version, tip=0)[source]¶

What a signature commits to besides the call: nonce, era, tip, chain.

Parameters:

nonce (int)
era (Era)
birth_hash (str)
genesis_hash (str)
spec_version (int)
transaction_version (int)
tip (int)

robonomicsinterface.extrinsic.compose_call(runtime, pallet, function, args=None)[source]¶

Encode pallet.function(**args) for this runtime.

Arguments are checked against the metadata: a missing or unknown one is an EncodeError, as is a value that does not fit its type.

Parameters:

runtime (Runtime)
pallet (str)
function (str)
args (Mapping[str, Any] | None)

Return type:

Call

robonomicsinterface.extrinsic.decode_events(records)[source]¶

Turn decoded System.Events records into Event objects.

Parameters:: records (list[dict[str, Any]])
Return type:: list[Event]

robonomicsinterface.extrinsic.dispatch_error_message(runtime, dispatch_error)[source]¶

Explain a DispatchError: (pallet, error, docs, message).

Parameters:

runtime (Runtime)
dispatch_error (Any)

Return type:

tuple[str | None, str, str, str]

robonomicsinterface.extrinsic.explain_invalid_transaction(raw)[source]¶

Decode a TransactionValidity: None if valid, else (kind, explanation).

raw is the answer of TaggedTransactionQueue_validate_transaction.

Parameters:: raw (bytes)
Return type:: tuple[str, str] | None

robonomicsinterface.extrinsic.extrinsic_hash(data)[source]¶

The hash nodes and explorers identify an extrinsic by.

Parameters:: data (bytes)
Return type:: str

robonomicsinterface.extrinsic.sign_extrinsic(runtime, call, keypair, context)[source]¶

Sign call with keypair as a version-4 extrinsic.

Parameters:

runtime (Runtime)
call (Call)
keypair (Keypair)
context (SigningContext)

Return type:

SignedExtrinsic

Keys and addresses¶

ED25519 and sr25519 accounts: key derivation, signatures and message encryption.

ED25519 runs on PyNaCl, sr25519 on the [sr25519] extra (keys_sr25519). Wire formats match substrate-interface byte for byte: the same mini secret from a mnemonic, the same ed25519 → curve25519 conversion and the same NaCl box with the nonce in front. Reports already encrypted by the 2.x stack stay readable, and the ones produced here open with the old tools.

class robonomicsinterface.keys.Keypair[source]¶

An ED25519 or sr25519 account, with or without its secret key.

Build one with a from_* class method; crypto_type picks the kind (ED25519 by default, so an existing mnemonic keeps its address). A keypair built from a public key or an address can verify signatures and be encrypted to, but not sign or decrypt. The secret is held only inside the signing key: the mnemonic or URI it came from is not kept, and neither repr() nor exceptions ever show it.

classmethod from_seed(seed, ss58_format=32, *, crypto_type=0)[source]¶

From a 32-byte seed (the Substrate “mini secret”), raw or as 0x hex.

Parameters:

seed (bytes | str)
ss58_format (int)
crypto_type (int | str)

Return type:

classmethod from_mnemonic(mnemonic, password='', ss58_format=32, *, crypto_type=0)[source]¶

From a BIP39 English mnemonic, as polkadot.js and substrate-interface derive it.

Parameters:

mnemonic (str)
password (str)
ss58_format (int)
crypto_type (int | str)

Return type:

classmethod from_uri(uri, ss58_format=32, *, crypto_type=0)[source]¶

From a Substrate secret URI: <phrase or 0x seed>//hard/soft///password.

An empty phrase means the development phrase, so //Alice gives the well-known development account. ED25519 has hard derivation only; a soft junction (/path) is refused. Use this for development and tests; for keys that people paste, use from_secret().

Parameters:

uri (str)
ss58_format (int)
crypto_type (int | str)

Return type:

classmethod from_secret(secret, ss58_format=32, *, crypto_type=0)[source]¶

From what a person may paste: a mnemonic or a raw 0x seed.

Derivation paths, and development keys such as //Alice with them, are refused on purpose: those secrets are public.

Parameters:

secret (str)
ss58_format (int)
crypto_type (int | str)

Return type:

classmethod from_json(backup, password, ss58_format=32)[source]¶

From the JSON backup a wallet exports (polkadot.js version 3) and its password.

The file says whether the account is ED25519 or sr25519, so nothing else is needed. The address in the file may be in any network’s format; the keypair gets ss58_format. Opening it takes a few seconds on a small board: call it off an event loop.

Raises:

InvalidKey – not a usable backup, or the wrong password.

Parameters:

backup (str | bytes | Mapping[str, Any])
password (str)
ss58_format (int)

Return type:

classmethod from_public_key(public_key, ss58_format=32, *, crypto_type=0)[source]¶

A counterparty known by its public key: can verify and be encrypted to.

Parameters:

public_key (bytes | str)
ss58_format (int)
crypto_type (int | str)

Return type:

classmethod from_address(address, ss58_format=None, *, crypto_type=0)[source]¶

A counterparty known by its SS58 address.

Parameters:

ss58_format (int | None) – when given, an address of another network is refused; otherwise the address’s own format is kept.
address (str)
crypto_type (int | str)

Return type:

An address carries no key type: say which it is with crypto_type. A wrong one only shows later, when a signature does not verify or a message does not decrypt.

static generate_mnemonic(word_count=12)[source]¶

A new random mnemonic; build the keypair with from_mnemonic().

Parameters:: word_count (int)
Return type:: str

property address: str¶: The SS58 address in this keypair’s format (32, Robonomics, by default).

sign(message)[source]¶

A 64-byte signature. A str is signed as its UTF-8 bytes.

An sr25519 signature is randomized: signing twice gives different bytes, and both verify.

Parameters:: message (bytes | str)
Return type:: bytes

encrypt_message(message, recipient_public_key, nonce=None)[source]¶

Encrypt for one recipient.

An ED25519 keypair makes a NaCl box with the 24-byte nonce in front; the recipient needs this keypair’s public key to open it. An sr25519 keypair makes an ECIES message (ecies_sr25519) from a one-time key, so its own key plays no part: nothing in the message names the sender, and a public-only keypair can encrypt too.

Parameters:

nonce (bytes | None) – for ED25519 test vectors only; a random nonce is used otherwise.
message (bytes | str)
recipient_public_key (bytes)

Return type:

bytes

decrypt_message(encrypted_message, sender_public_key)[source]¶

Open what encrypt_message() made (an ED25519 box may be from substrate-interface).

sender_public_key opens an ED25519 box; an sr25519 message carries its own one-time key, so the argument is not used.

Parameters:

encrypted_message (bytes)
sender_public_key (bytes)

Return type:

bytes

SS58 addresses: a network prefix, a 32-byte public key and a blake2b checksum.

robonomicsinterface.ss58.address_format(address)[source]¶

The SS58 network format an address is encoded with.

Parameters:: address (str)
Return type:: int

robonomicsinterface.ss58.decode_address(address, ss58_format=None)[source]¶

Return the 32-byte public key behind an address.

Parameters:

ss58_format (int | None) – when given, an address of any other network is refused.
address (str)

Return type:

bytes

robonomicsinterface.ss58.encode_address(public_key, ss58_format=32)[source]¶

Encode a 32-byte public key (account id) as an SS58 address.

Parameters:

public_key (bytes)
ss58_format (int)

Return type:

robonomicsinterface.ss58.is_valid_address(address, ss58_format=32)[source]¶

Whether the text is a valid address of the given format (any format if None).

Parameters:

address (str)
ss58_format (int | None)

Return type:

bool

BIP39 English mnemonics and the mini secret Substrate derives from them.

Substrate does not use the standard BIP39 seed. It derives a 32-byte “mini secret” from the mnemonic’s entropy, not from the mnemonic string, with PBKDF2-HMAC-SHA512 over 2048 rounds (substrate-bip39::seed_from_entropy). The standard seed would give a different address from the same words, which is why the tests pin this against vectors from substrate-interface.

robonomicsinterface.bip39.generate_mnemonic(word_count=12)[source]¶

Generate a new random mnemonic from the system CSPRNG.

Parameters:: word_count (int)
Return type:: str

robonomicsinterface.bip39.validate_mnemonic(mnemonic)[source]¶

Whether the text is a valid mnemonic, words and checksum.

Parameters:: mnemonic (str)
Return type:: bool

Report envelope¶

The multi-recipient envelope: one symmetric key, wrapped for every recipient.

The payload is encrypted once with a random key for NaCl’s SecretBox, and that key is encrypted separately, with Keypair.encrypt_message(), for each address that may open it. The serialized form is the one already published by Robonomics Report Service:

{"data": "0x<secretbox>", "keys": {"<address>": "0x<box of the key>", ...}}

Optional metadata travels inside the encrypted payload as {"payload": <data>, "meta": {...}}; parse_decrypted() splits it.

A package has one key type, the sender’s: ED25519 senders wrap the key in NaCl boxes for ED25519 recipients, sr25519 senders in ECIES messages for sr25519 recipients. An address does not say which kind it is, so every recipient is taken to be of the sender’s kind; the recipient’s own key says how to open it.

robonomicsinterface.envelope.decrypt_package(package, recipient, sender_address)[source]¶

Unwrap the key addressed to recipient, then decrypt the payload.

sender_address opens an ED25519 box; an sr25519 message carries its own one-time key, so it is not used for an sr25519 recipient.

Raises:

PackageError – the package is malformed or has no key for this recipient.
PayloadError – the key or the payload does not decrypt.

Parameters:

package (str | bytes)
recipient (Keypair)
sender_address (str)

Return type:

robonomicsinterface.envelope.encrypt_for_recipients(data, sender, recipients, metadata=None)[source]¶

Encrypt data once and wrap its key for each recipient address.

The sender is always added as a recipient, so it can read back what it sent. Every recipient is taken to have the sender’s key type. Returns the JSON package.

Parameters:

data (str)
sender (Keypair)
recipients (Iterable[str])
metadata (dict[str, Any] | None)

Return type:

robonomicsinterface.envelope.parse_decrypted(text)[source]¶

Split {"payload": ..., "meta": ...}; plain data comes back without meta.

Parameters:: text (str)
Return type:: tuple[str, dict[str, Any] | None]

Errors¶

Exceptions raised by the library.

Everything derives from RobonomicsError, so a caller can catch the library as a whole. Input errors also derive from ValueError: they describe bad data, and retrying them is pointless.

Messages never contain secrets: no mnemonic, seed or private key is ever formatted into an exception, including the input that failed to parse.

exception robonomicsinterface.errors.RobonomicsError[source]¶

Bases: Exception

Base class for every error raised by robonomics-interface.

exception robonomicsinterface.errors.InvalidMnemonic[source]¶

The text is not a valid BIP39 English mnemonic.

exception robonomicsinterface.errors.InvalidAddress[source]¶

The text is not a valid SS58 address, or it has an unexpected format.

exception robonomicsinterface.errors.InvalidKey[source]¶

A seed, public key or derivation path cannot be used.

exception robonomicsinterface.errors.NoSecretKey[source]¶

The keypair holds a public key only, so it cannot sign or decrypt.

exception robonomicsinterface.errors.DecryptionError[source]¶

A box does not open: wrong keys, or the ciphertext was damaged.

exception robonomicsinterface.errors.MetadataError[source]¶

The runtime metadata cannot be used, or does not describe what was asked.

exception robonomicsinterface.errors.NoSuchPallet[source]¶

The runtime has no pallet with this name.

exception robonomicsinterface.errors.NoSuchStorage[source]¶

The pallet has no storage item with this name.

exception robonomicsinterface.errors.NoSuchConstant[source]¶

The pallet has no constant with this name.

exception robonomicsinterface.errors.NoSuchCall[source]¶

The pallet has no call (extrinsic function) with this name.

exception robonomicsinterface.errors.UnsupportedExtension[source]¶

Bases: MetadataError

The runtime requires a signed extension this library cannot fill in.

exception robonomicsinterface.errors.EncodeError[source]¶

A value does not fit the type the runtime expects, e.g. a bad storage key.

exception robonomicsinterface.errors.DecodeError[source]¶

Bytes from the chain do not decode as the type the metadata describes.

exception robonomicsinterface.errors.TransportError[source]¶

The node could not be reached or stopped answering. Retrying may help.

Every subclass is a network-level failure: the request may not have reached the node at all, so nothing is known about its effect.

exception robonomicsinterface.errors.ConnectionFailed(endpoint, reason)[source]¶

Bases: TransportError

A connection to an endpoint could not be opened, or the node is unusable.

Parameters:

endpoint (str)
reason (str)

Return type:

None

exception robonomicsinterface.errors.ConnectionLost[source]¶

Bases: TransportError

The connection closed while a request or subscription was in flight.

exception robonomicsinterface.errors.RequestTimeout[source]¶

Bases: TransportError, TimeoutError

The node did not answer in time.

exception robonomicsinterface.errors.AllEndpointsFailed(failures)[source]¶

Bases: TransportError

No endpoint could be used; failures says why for each of them.

Parameters:: failures (list[ConnectionFailed])
Return type:: None

exception robonomicsinterface.errors.RpcError(method, code, message, data=None)[source]¶

The node answered with a JSON-RPC error. Repeating the same request will not help.

Parameters:

method (str)
code (int | None)
message (str)
data (object)

Return type:

None

exception robonomicsinterface.errors.TransactionError[source]¶