astreum 0.5.5

Python library to interact with the Astreum blockchain and its virtual machine.

lib

Python library to interact with the Astreum blockchain and its virtual machine.

View on PyPI

Configuration

When initializing an astreum.Node, pass a dictionary with any of the options below. Only the parameters you want to override need to be present – everything else falls back to its default.

Core Configuration

Parameter	Type	Default	Description
chain	string	"test"	Chain name ("main" or "test"). If chain_id is omitted, main maps to 1; all other values default to test (0).
chain_id	int	0	Chain identifier used for validation (0 = test, 1 = main). If chain is omitted, chain is derived from this value (1 => main, otherwise test).
hot_storage_limit	int	1073741824	Maximum bytes kept in the hot cache before new atoms are skipped (1 GiB).
cold_storage_limit	int	10737418240	Cold storage write threshold (10 GiB by default); set to 0 to skip the limit.
cold_storage_path	string	None	Directory where persisted atoms live; Astreum creates it on startup and skips cold storage when unset.
cold_storage_scale	string	"MB"	Base unit for cold storage roll-up thresholds (KB, MB, or GB). This sets the derived cold_storage_base_size used for level_0 collation and higher-level merges.
atom_fetch_interval	float	0.25	Poll interval (seconds) while waiting for missing atoms in get_atom_list_from_storage; 0 disables waiting.
atom_fetch_retries	int	8	Number of poll attempts for missing atoms; max wait is roughly interval * retries, 0 disables waiting.
verify_blockchain_interval	float	10.0	Delay (seconds) between consensus verification worker iterations. Defaults to peer_timeout_interval when not explicitly set.
verification_max_stale_seconds	int	10	Ignore otherwise-valid candidate heads whose block timestamp is older than this many seconds when selecting the latest verified chain head.
verification_max_future_skew	int	2	Ignore candidate heads whose block timestamp is more than this many seconds in the future when selecting the latest verified chain head.
latest_block_hash	hex string	None	Optional 32-byte block-hash override used to preload the node's starting latest_block_hash from config.
verified_up_to	hex string	None	Optional 32-byte hash override used to preload the verification anchor (node.verified_up_to) from config.
logging_enabled	bool	True	When False, disable logger setup entirely, including file creation and the background logging listener thread.
logging_retention_days	int	7	Number of days to keep rotated log files (daily gzip).
verbose	bool	False	When True, also mirror JSON logs to stdout with a human-readable format.

Communication

Parameter	Type	Default	Description
relay_secret_key	hex string	Auto-generated	X25519 private key used for the relay route; a new keypair is created when this field is omitted.
relay_payment_secret_key	hex string	None	Optional Ed25519 private key used for relay/storage payment channels; when set, the node can advertise a relay payment public key for paid objects.
validation_secret_key	hex string	None	Optional Ed25519 key that lets the node join the validation route; leave blank to opt out of validation.
use_ipv6	bool	False	Bind the incoming/outgoing sockets on IPv6 (the OS still listens on IPv4 if a peer speaks both).
port	int	52780	UDP port the relay binds to; pass 0 or omit to let the OS pick an ephemeral port.
default_seed	string	"bootstrap.astreum.org:52780"	Default address to ping before joining; set to None to disable the built-in default.
additional_seeds	list[str]	[]	Extra addresses appended to the bootstrap list; each must look like host:port or [ipv6]:port.
peer_timeout	int	900	Evict peers that have not been seen within this many seconds (15 minutes).
peer_timeout_interval	int	10	How often (seconds) the peer manager checks for stale peers.
bootstrap_retry_interval	int	30	How often (seconds) to retry bootstrapping when the peer list is empty.
storage_index_interval	int	600	How often (seconds) to re-advertise entries in node.atom_advertisments to the closest known peer.
storage_request_minimum_price	int	1	Floor price for storage/object requests; the dynamic storage request price never drops below this value.
storage_request_price_interval	float	5.0	How often (seconds) the storage thread recomputes request pricing from inbound queue pressure.
fair_use_limit	int	1048576	Bytes a peer may receive via shared object uploads before fair-use ratio enforcement begins (1 MiB by default).
fair_use_ratio	float	0.5	Minimum download/upload ratio a peer must maintain after fair_use_limit is exceeded; set 0 to disable the fair-use gate.
incoming_queue_size_limit	int	67108864	Soft cap (bytes) for inbound queue usage tracked by enqueue_incoming; set to 0 to disable.
incoming_queue_timeout	float	1.0	When > 0, enqueue_incoming waits up to this many seconds for space before dropping the payload.

Advertisements: node.atom_advertisments holds (atom_id, payload_type, expires_at) tuples. Use node.add_atom_advertisement or node.add_atom_advertisements to enqueue entries (expires_at=None keeps them indefinite). Validators automatically advertise block, transaction (main and detail lists), receipt, and account trie lists for 15 minutes by default.

Note The peer‑to‑peer route used for object discovery is always enabled. If validation_secret_key is provided the node automatically joins the validation route too.

Usage

from astreum.node import Node

config = {
    "relay_secret_key": "ab…cd",             # optional – hex encoded
    "validation_secret_key": "12…34",        # optional – validator
    "hot_storage_limit": 1073741824,         # cap hot cache at 1 GiB
    "cold_storage_limit": 10737418240,       # cap cold storage at 10 GiB
    "cold_storage_path": "./data/node1",
    "port": 52780,
    "use_ipv6": False,
    "default_seed": None,
    "additional_seeds": [
        "127.0.0.1:7374"
    ]
}

node = Node(config)
# … your code …

Validation Overview

Call node.verify() to connect the node, initialize fork tracking, and start the background consensus verification worker. The worker watches peer-reported block heads, verifies candidate forks, merges fully verified forks, and updates node.latest_block_hash / node.latest_block when a better verified head is available.

node.verify()

node.verify() is idempotent while the verification thread is already running.

To start creating blocks, call node.validate(validation_secret_key). Validation connects the node, prepares validator state, creates a genesis block when no latest block is configured, and starts the consensus validation worker.

from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey

validation_secret_key = Ed25519PrivateKey.generate()

node.validate(validation_secret_key)

The validation worker only creates blocks when this node is the scheduled validator for the current head. It applies queued transactions when available, can create empty blocks when the queue is empty, stores the new block atoms locally, advertises them to peers, and updates node.latest_block_hash / node.latest_block.

Transaction Overview

Use send_transaction(...) to atomize, store, advertise, and forward an already-signed transaction to available validators.

from astreum.consensus.transaction import (
    create_transaction,
    send_transaction,
)

tx = create_transaction(
    chain_id=node.config["chain_id"],
    amount=100,
    counter=sender_account.counter + 1,
    recipient=recipient_public_key,
    sender=sender_public_key,
)
tx.sign(sender_key)
tx_hash = send_transaction(node, tx)
print(tx_hash.hex())

The node must already be connected and have a latest_block; otherwise the function raises RuntimeError. It writes the transaction's atoms to local storage, advertises them on the P2P network, and sends the transaction hash to peers on the validation route.

Query API

Query functions let you fetch blocks and search transactions by height or attribute from the chain tip.

from astreum import get_block, find_transactions

get_block(node, *, height)

Fetch a single block by its chain height. Returns the Block object or None if the block hasn't been mined yet or isn't reachable.

Parameter	Type	Description
node	Node	An initialised, connected Astreum node.
height	int	The target block height. Must be ≤ the node's latest block.

block = get_block(node, height=100_000)
if block:
    print(f"block hash: {block.expr_id.hex()[:16]}...")
    print(f"tx count:   {len(block.transactions) if block.transactions else 0}")

Internally walks the previous_block chain to the target era, then binary-descents the bloom tree by offset — approximately 11 storage fetches (O(log N)) plus the chain walk.

find_transactions(node, *, sender, receiver, …)

Search for transactions matching the given filters. All filter parameters are optional — leave a filter at its default (32 zero bytes) to match anything.

When multiple filters are set, only transactions matching all of them are returned (AND semantics).

Parameter	Type	Default	Description
node	Node	—	An initialised, connected Astreum node.
tx_hash	bytes	ZERO32	Match a specific transaction hash.
sender	bytes	ZERO32	Filter by sender public key.
receiver	bytes	ZERO32	Filter by recipient public key.
key	bytes	ZERO32	Filter by contract bloom key (from bloom.put).
start_height	int	node.latest_block.height	Search backward from this height.
end_height	int	0	Stop when blocks drop below this height.
limit	int	1	Max results; pass 0 for no limit.

# Find up to 10 transactions from a specific sender
txs = find_transactions(node, sender=addr, limit=10)

# Find transactions in a specific height range
txs = find_transactions(
    node,
    receiver=addr,
    start_height=50_000,
    end_height=40_000,
    limit=5,
)

Each returned Transaction has its block_hash field set to the expr hash of the block that included it, so you can locate the containing block.

Internally uses the bloom tree index to skip eras that can't contain a match, then walks individual blocks inside candidate eras.

Language Syntax

Astreum Language is a homoiconic, stack-based concatenative language with runtime reflection and actor support. It has a functional programming style, but also supports state and effects; deterministic mode disables runtime effects and loading, making it suitable for on-chain evaluation.

Astreum uses S-expressions with prefix notation. Expressions are either atoms or parenthesised lists. Lists are right-linked Link chains — (a b c) parses as Link(a, Link(b, c)).

Tokens

Token	Meaning
( )	Delimit a list expression.
'	Quote token — when alone, parses as the symbol '. Inside a list it's a regular symbol.
123 -5	Integer literals. Parsed to Expr.Int.
3.14 -2.5	Float literals. Parsed to Expr.Float.
"hello world"	String literals. Everything between double quotes is one token (spaces, parens preserved). Parsed to Expr.String.
0x1f 0Xab	Hex bytes. Raw hex digits, no two's complement. Parsed to Expr.Bytes.
add def	Everything else is a symbol. Parsed to Expr.Symbol.
;	Line comment — skips to end of line.
#;	Expression skip — skips the next complete expression (including nested lists).

Expression types

Type	Class	Description
Symbol	Expr.Symbol(value: str)	A named identifier.
Bytes	Expr.Bytes(value: bytes)	Raw byte data.
Int	Expr.Int(value: int)	Arbitrary-precision signed integer.
Float	Expr.Float(value: float)	IEEE 754 double-precision float.
String	Expr.String(value: str)	UTF-8 string content.
Link	Expr.Link(head, tail)	A pair — the building block for lists. Link(None, None) is NIL.

Links form right-associated chains. (1 2 3) becomes:

Link(Int(1), Link(Int(2), Int(3)))

Environment

Env(data={}, parent=None) is a string-keyed binding store with parent-chain lookup. env.get(key) walks up parent environments. env.put(key, value) writes to the local environment only.

Machine Overview

The machine evaluates an expression tree against an environment, producing a result stack.

from astreum.machine.main import Machine
from astreum.machine import Env, Expr, tokenize, parse
from astreum.node import Node

node = Node()
machine = Machine(node)

# Parse source text and evaluate
tokens = tokenize("(1 2 +)")
expr, _ = parse(tokens)

env = Env()
result = machine.run(expr, env)
# result = Int(3)

machine.run(expr, env) walks the expression tree and returns the top value of the result stack (or NIL if the stack is empty). Symbols that match operators pop arguments and push results. Non-operator symbols are looked up in the environment. Bytes, Int, Float, and String values are pushed as-is.

The Machine constructor accepts a mode parameter ("dynamic" or "deterministic", default "dynamic"). In deterministic mode the operators spawn, send, receive, eval, ref, and load push NIL instead of executing — this ensures reproducible evaluation for contexts such as block validation.

Metering

Every Machine carries a Meter that tracks computation cost in bytes read:

machine = Machine(node, meter_enabled=True, meter_limit=1_000_000)
# MeterExceededError raised if limit is exceeded
machine.meter.used  # bytes consumed so far

Error handling

Operators raise OpError on type mismatches, stack underflow, out-of-bounds access, or other semantic errors. The dispatch layer catches OpError and responds differently depending on the operator name:

• Bare form (+, /, split, …) — catches the error and pushes NIL (Link(None, None)). The program continues with NIL on the stack.
• Tagged form (+?, /?, split?, …) — appending ? to any primitive operator name wraps the result as a tagged pair:
  • Success: (ok . result_value) — or (ok . NIL) for void operators (drop?, dup?, etc.)
  • Error: (err . "error message") — the message string describes what went wrong.

MeterExceededError is never caught and always propagates.

from astreum.machine.main import Machine
from astreum.machine import tokenize, parse, Expr

machine = Machine(node=None)

# Bare form: error pushes NIL
result = machine.run(*parse(tokenize("(drop)")))

# Tagged form: error wraps as (err . reason)
result = machine.run(*parse(tokenize("(drop?)")))

# Tagged form: success wraps as (ok . value)
result = machine.run(*parse(tokenize("(7 8 +?)")))

Operators

Operators are symbols that pop arguments from the stack and push a result. Any primitive operator can be suffixed with ? to wrap the result as (ok v) on success or (err reason) on error (see Error handling).

Operator	Stack effect	Description
+	a b → sum	Addition. Int/Int → Int, Float/Float → Float, Int+Float → Float (promotion). Overflow on int→float conversion raises OpError.
-	a b → diff	Subtraction. Same type rules as +.
*	a b → prod	Multiplication. Same type rules as +.
/	a b → quot	Division. Int/Int → integer division (//), Float/Float → float division. Division by zero raises OpError.
%	a b → rem	Modulo (Int only). Raises OpError on non-Int.
sqrt	a → sqrt(a)	Square root (Float only). Raises OpError on non-Float or negative.
abs	a → abs(a)	Absolute value (Int or Float). Raises OpError on non-numeric input.
&	a b → a&b	Bitwise AND (Bytes).
|	a b → a|b	Bitwise OR (Bytes).
^	a b → a^b	Bitwise XOR (Bytes).
~	a → ~a	Bitwise NOT (Bytes, one's complement within the operand's byte width).
<<	value shifts → result	Shift: value (Bytes or Int) left by shifts (Int > 0) or right by shifts (Int < 0). For Bytes the shift is logical (zero-fill), for Int it is arithmetic (sign-extend). No-op on 0. Raises OpError on type mismatch.
<<<	value shifts → result	Rotate: value (Bytes or Int) left by shifts (Int > 0) or right by shifts (Int < 0). Rotation width is byte-rounded for Int. No-op on 0. Raises OpError on type mismatch.
dip	v (expr) → ... v	Temporarily remove v, evaluate (expr) on the remaining stack, then push v back. Raises OpError on underflow.
drop	a → —	Pop and discard one value. Raises OpError on underflow.
dup	a → a a	Pop and push the same value twice. Raises OpError on underflow.
swap	a b → b a	Pop two values and push them back in reversed order. Raises OpError on underflow.
rot	a b c → b c a	Rotate the top three stack values left. Raises OpError on underflow.
link	head tail → Link(head, tail)	Construct a Link pair.
head	Link(h, t) → h	Extract the head of a Link; raises OpError on non-Link.
tail	Link(h, t) → t	Extract the tail of a Link; raises OpError on non-Link.
is_atom	expr → 0|1	Pushes Bytes(b"\\x01") if the value is not a Link, else Bytes(b"\\x00").
is_eq	a b → 0|1	Structural equality: atoms compared by value; Link by recursive head+tail. Different types are never equal.
<	a b → 0|1	Less than (Int/Int or Float/Float). Pushes Bytes(b"\\x01") if true, else Bytes(b"\\x00"). Raises OpError on type mismatch.
>	a b → 0|1	Greater than. Same type rules as <.
<=	a b → 0|1	Less than or equal. Same type rules as <.
>=	a b → 0|1	Greater than or equal. Same type rules as <.
if	(cond) then else → result	Evaluate cond quotation; if truthy evaluate then, otherwise evaluate else.
rec	pred then_branch rec1 rec2 → result	Tail/general recursion loop. Evaluates pred; if truthy evaluates then_branch. Otherwise evaluates rec1, recurses, then evaluates rec2 on return.
fn	argN … arg1 params body → result	Pops params (Link chain of Symbols), body, and N args. Binds args to param names in a child environment (parent = call-site env) and evaluates body.
lambda	argN … arg1 params body → result	Same as fn but with parent=None — body can only access parameters and built-in operators.
def	name value → —	Binds name (Symbol) to value in the current environment. Write-once: if the name already exists in the target env, def is a no-op (pushes NIL).
'	(' X) → X	Quote special form — wraps a single unevaluated expression. (' 42) pushes Int(42).
quote	a → (' a)	Stack operator — pops a value and pushes it back wrapped in a (' …) quotation.
eval	expr → result|nil	Pop an expression and evaluate it as code in the current environment. Raises OpError on underflow. In deterministic mode pushes NIL.
ref	hash → expr|nil	Resolve a 32-byte hash to its stored expression (node.get_expr). For Link values, returns thunk-wrapped (head_h ref) / (tail_h ref) for lazy traversal. Raises OpError on non-Bytes or wrong-size input. In deterministic mode pushes NIL.
load	hash → full_expr|nil	Deep-resolve a 32-byte hash recursively through the entire sub-tree (node.get_expr_full). Cost is 2× the resolved expression size. Raises OpError on non-Bytes or wrong-size input. In deterministic mode pushes NIL.
symbol	a → symbol|nil	Convert Bytes (UTF-8 decoded), String, Int, or Float to Expr.Symbol. Raises OpError on invalid UTF-8.
str	a → string|nil	Convert any atom to Expr.String. Raises OpError on unsupported type.
float	a → float|nil	Convert Int, Bytes (exactly 8 bytes, IEEE 754 LE), String, or Symbol to Expr.Float.
int	a → int|nil	Convert Bytes (LE signed), String, Symbol, or Float to Expr.Int.
bytes	a → bytes|nil	Convert Int (variable-length signed), Float (8-byte IEEE 754 LE), String, or Symbol (UTF-8) to Expr.Bytes.
concat	a b → concatenation	Concatenate two Bytes objects. Raises OpError on non-Bytes.
split	value index → Link(left, right)	Split Bytes value at index (Int), returning Link(left, right). Raises OpError on out-of-bounds or type mismatch.
size	value → length	Return length of Bytes value as Int. Raises OpError on non-Bytes.
index	value index → byte	Return the single-byte Bytes at index of a Bytes value. Raises OpError on out-of-bounds or type mismatch.

Actor Model

The machine supports concurrent actors communicating via named mailboxes.

Operator	Stack effect	Description
spawn	body name → name|nil	Spawn a new actor thread running body in a child environment. name must be a Symbol. Raises OpError on non-symbol name or non-Link body. Returns NIL if the name is already taken or threading is disabled. In deterministic mode pushes NIL.
send	target msg → —	Send msg to the mailbox of actor target. target must be a Symbol. Raises OpError on non-symbol target or if the mailbox doesn't exist. In deterministic mode pushes NIL.
receive	target → msg|nil	Block until a message arrives in the mailbox of actor target. Returns NIL if the mailbox doesn't exist. Raises OpError on non-symbol target. In deterministic mode pushes NIL.

Actors run on daemon threads with their own environment (parented to the spawner's environment). In deterministic mode spawn, send, receive, eval, ref, and load push NIL — they either require concurrency, runtime code-as-data, or external content lookup, all of which are disabled there for reproducible evaluation.

Quickstart Example

from astreum.machine.main import Machine
from astreum.machine import Env, Expr, tokenize, parse, Meter
from astreum.node import Node

node = Node()
machine = Machine(node)

# Call an fn inline: (3 5 (quote ($0 $1)) (quote ($0 $1 +)) fn)
# Then add 2 to the result
src = "((3 5 (quote ($0 $1)) (quote ($0 $1 +)) fn) 2 +)"
tokens = tokenize(src)
expr, _ = parse(tokens)

env = Env()
result = machine.run(expr, env)

print(result.value)  # 10

Parse errors

tokenize and parse raise ParseError (from astreum.machine.parser) on malformed input:

from astreum.machine import tokenize, parse, ParseError

try:
    tokens = tokenize("(1 2")
    expr, _ = parse(tokens)
except ParseError as e:
    print("Parse failed:", e)

Runtime errors during evaluation raise OpError and are caught by the dispatch layer — see Error handling.

---

Logging

Every Node instance wires up structured logging automatically:

• Set config["logging_enabled"] = False to skip logging setup entirely. This bypasses log directory creation, file rotation, console mirroring, and the background listener thread.
• Logs land in per-instance files named node.csv under %LOCALAPPDATA%\Astreum\lib-py\logs/<instance_id> on Windows and $XDG_STATE_HOME (or ~/.local/state)/Astreum/lib-py/logs/<instance_id> on other platforms. The <instance_id> is the first 16 hex characters of a BLAKE3 hash of the caller's file path, so running the node from different entry points keeps their logs isolated.
• Files rotate at midnight UTC with gzip compression (node-YYYY-MM-DD.csv.gz) and retain 7 days by default. Override via config["logging_retention_days"].
• Each event is a single CSV row with columns ts, level, msg, module, and func.
• Set config["verbose"] = True to mirror logs to stdout in a human-friendly format like [2025-04-13-42-59] [info] Starting Astreum Node.
• The very first entry emitted is the banner Starting Astreum Node, signalling that the logging pipeline is live before other subsystems spin up.

Testing

python3 -m venv venv
source venv/bin/activate
pip install -e .

for all tests

python3 -m unittest discover -s tests

for individual tests

Test	Method	Pass
tests/node/machine/parser.py	python3 -m unittest tests.node.machine.parser	✅
tests/node/machine/tagged_results.py	python3 -m unittest tests.node.machine.tagged_results	✅
tests/node/test_node_init.py	python3 -m unittest tests.node.test_node_init	✅
tests/node/test_node_connection.py	python3 -m unittest tests.node.test_node_connection	✅
tests/node/test_current_validator.py	python3 -m unittest tests.node.test_current_validator	✅
tests/machine/operators/ (all)	python3 -m unittest discover -s tests/machine/operators -p "*.py"	✅
tests/block/expr.py	—	✅
tests/block/nonce.py	—	✅
tests/communication/test_message_port.py	python3 -m unittest tests.communication.test_message_port	✅
tests/communication/test_integration_port_handling.py	—	✅
tests/consensus/genesis.py	python3 -m unittest tests.consensus.genesis	✅
tests/consensus/transaction/test_apply.py	—	✅
tests/crypto/bloom_filter.py	python3 -m unittest tests.crypto.bloom_filter	✅
tests/crypto/bloom_tree.py	python3 -m unittest tests.crypto.bloom_tree	✅
tests/models/test_patricia.py	python3 -m unittest tests.models.test_patricia	✅
tests/storage/indexing.py	python3 -m unittest tests.storage.indexing	✅
tests/storage/cold.py	python3 -m unittest tests.storage.cold	✅
tests/utils/test_logging.py	—	✅