Version: Next

Virtual File System

The AXONE logic Virtual File System (VFS) is the capability surface exposed to Prolog programs. Programs do not read the node filesystem directly. They resolve versioned /v1/... paths mounted by the AXONE blockchain to load AXONE libraries, inspect the current execution context, read chain-backed state, or call chain services.

Most programs should use the predicates documented in this section. The VFS paths matter when you are composing lower-level predicates, auditing what a wrapper does, or integrating a capability that does not yet have a dedicated predicate.

`/v1`

The path determines the protocol:

Path family	Open mode	Stream type	What changes for callers
`/v1/lib/...`	`read` or `consult/1`	Text	Loads Prolog source provided by the AXONE blockchain.
`/v1/run/...`	`read`	Text	Reads immutable data for the current logic execution.
`/v1/var/lib/...`	`read`	Text	Reads deterministic chain-backed state exposed to logic.
`/v1/dev/...`	`read_write`	Text or binary	Writes a request, then reads the response from a transactional endpoint.

Read-only paths usually return Prolog terms terminated by .. Always close the stream you open:

setup_call_cleanup(
  open('/v1/run/header/height', read, Stream, [type(text)]),
  read_term(Stream, Height, []),
  close(Stream)
).

Transactional paths under /v1/dev/... follow a half-duplex protocol. The first read commits the request; after that the stream is response-only and further writes fail. Prefer dev_call/4 from /v1/lib/dev.pl when you need direct device access:

:- consult('/v1/lib/dev.pl').

call_device(Path, RequestBytes, ResponseBytes) :-
  dev_call(Path, binary, dev_write_bytes(RequestBytes), dev_read_bytes(ResponseBytes)).

Device calls are bounded by request and response size limits. Use the wrapper predicates listed below when they exist; they encode the expected request shape and error mapping for the target capability.

`/v1/lib/*.pl`

AXONE embeds reusable Prolog libraries under /v1/lib. Load them with consult/1; they are Prolog source files.

Field	Value
Paths	`/v1/lib/*.pl`
Open mode	`read`, usually through `consult/1`
Stream type	Text
Response	Prolog source code

Example:

:- consult('/v1/lib/chain.pl').
:- consult('/v1/lib/bank.pl').

`/v1/run/header`

The /v1/run/header paths expose the SDK header snapshot for the current logic execution. Use them when the relation depends on the AXONE block context.

Field	Value
Paths	`/v1/run/header/@`, `/v1/run/header/height`, `/v1/run/header/hash`, `/v1/run/header/time`, `/v1/run/header/chain_id`, `/v1/run/header/app_hash`
Open mode	`read`
Stream type	Text
Response	One Prolog term. `@` returns a `header{...}` dict; field paths return the selected field.
Recommended predicate	`header_info/1` from `/v1/lib/chain.pl`

Example:

:- consult('/v1/lib/chain.pl').

current_height(Height) :-
  header_info(Header),
  Height = Header.height.

`/v1/run/comet`

The /v1/run/comet paths expose CometBFT block data attached to the current execution, such as validator information, proposer address, evidence, and last commit data.

Field	Value
Paths	`/v1/run/comet/@`, `/v1/run/comet/validators_hash`, `/v1/run/comet/proposer_address`, `/v1/run/comet/evidence`, `/v1/run/comet/last_commit`, `/v1/run/comet/last_commit/round`, `/v1/run/comet/last_commit/votes`
Open mode	`read`
Stream type	Text
Response	One Prolog term. `@` returns a `comet{...}` dict; field paths return the selected field.
Recommended predicate	`comet_info/1` from `/v1/lib/chain.pl`

`/v1/run/source/files`

/v1/run/source/files lists the Prolog source files loaded in the current interpreter.

Field	Value
Path	`/v1/run/source/files`
Open mode	`read`
Stream type	Text
Response	One Prolog list of source file atoms
Recommended predicate	`source_file/1`

`/v1/var/lib/bank/<address>`

The /v1/var/lib/bank/<address> paths expose account balances from AXONE chain state. <address> must be a valid account Bech32 address.

Field	Value
Paths	`/v1/var/lib/bank/<address>/balances/@`, `/v1/var/lib/bank/<address>/spendable/@`, `/v1/var/lib/bank/<address>/locked/@`
Open mode	`read`
Stream type	Text
Response	A stream of `Denom-Amount` Prolog terms, one term per coin
Recommended predicates	`bank_balances/2`, `bank_spendable_balances/2`, `bank_locked_balances/2` from `/v1/lib/bank.pl`

Amounts are integers when they fit in int64; larger amounts are atoms preserving the full decimal value.

`/v1/var/lib/staking/<delegator>`

The /v1/var/lib/staking/<delegator> paths expose staking-module positions for an account. <delegator> must be a valid account Bech32 address.

Field	Value
Paths	`/v1/var/lib/staking/<delegator>/delegations/@`, `/v1/var/lib/staking/<delegator>/unbonding_delegations/@`, `/v1/var/lib/staking/<delegator>/redelegations/@`
Open mode	`read`
Stream type	Text
Response	A stream of Prolog terms, one term per staking position
Recommended predicates	`staking_delegations/2`, `staking_unbonding_delegations/2`, `staking_redelegations/2`, `staking_delegations_to_bonded_validators/2`, and `staking_bonded_delegated_balance/2` from `/v1/lib/staking.pl`

Delegations include all validator bond statuses. They do not imply that the validator belongs to the active staking validator set. The bonded predicates join delegations with the bonded validator view below; they do not add a jailed filter. Unbonding and redelegation entries are lifecycle information, not extra delegated balances to add to this total. Rewards belong to the distribution module and are not included.

Coin amounts use coin(Denom, Amount). Amounts are integers when they fit in int64, otherwise decimal atoms. The bonded balance predicate preserves exact precision, rejects mismatching denominations, and returns coin(BondDenom, 0) for an empty eligible collection.

`/v1/var/lib/staking/validators/<status>/@`

This read-only text stream exposes validators with the requested Cosmos bond status. <status> is bonded, unbonding, or unbonded. The query is paginated and each term is validator{operator: Operator, status: Status}, where Operator is the validator operator address atom. Jailed status is not a separate filter.

Use staking_validators/2 to select a bond status, or staking_bonded_validators/1 for BOND_STATUS_BONDED.

`/v1/var/lib/staking/params/@`

This read-only text snapshot exposes staking_params{bond_denom: Denom}. staking_bonded_delegated_balance/2 uses it to give zero balances their staking denomination and to prevent addition across denominations.

`/v1/var/lib/logic/users/<publisher>/programs/<program_id>.pl`

Published logic programs are exposed as Prolog source files. This lets a program load another program that has been published on AXONE chain state.

Field	Value
Path	`/v1/var/lib/logic/users/<publisher>/programs/<program_id>.pl`
Open mode	`read`, usually through `consult/1`
Stream type	Text
Response	Prolog source code
Recommended predicate	`consult/1`

<publisher> is the publisher account address. <program_id> is the hex program identifier.

`/v1/dev/codec/<codec>`

Codec paths transform data through codecs supported by the AXONE blockchain. They are transactional endpoints: open in read_write, write the complete request, then read the serialized response term.

Field	Value
Path	`/v1/dev/codec/<codec>`
Open mode	`read_write`
Stream type	Text
Request	Command plus payload. Shape depends on the codec.
Response	One serialized Prolog term, usually `ok(Value)` or `error(Code)`
Recommended predicates	`bech32_address/2`, `json_prolog/2`, `json_read/2`, `json_write/2`, and text helpers such as `string_bytes/3`

`/v1/dev/codec/bech32`

The Bech32 codec converts between AXONE Bech32 atoms and Hrp-Bytes Prolog pairs.

Field	Value
Path	`/v1/dev/codec/bech32`
Request	`encode <hrp> <hex_bytes>` or `decode <bech32>`
Response	`ok(Bech32)`, `ok(Hrp-Bytes)`, or `error(Code)`
Recommended predicate	`bech32_address/2` from `/v1/lib/bech32.pl`

`/v1/dev/codec/json`

The JSON codec converts between JSON text and AXONE's canonical Prolog JSON representation.

Field	Value
Path	`/v1/dev/codec/json`
Request	`decode` followed by JSON text, or `encode` followed by a canonical Prolog JSON term
Response	`ok(Value)` or `error(Code)`
Recommended predicates	`json_prolog/2`, `json_read/2`, `json_write/2` from `/v1/lib/json.pl`

Canonical JSON terms use json(NameValueList) for objects, lists for arrays, atoms for strings, numbers for JSON numbers, and @(true), @(false), and @(null) for booleans and null.

Empty decode payloads are rejected with error(syntax_error(json(eof))). Callers that previously used an empty payload to represent JSON null must send the literal null instead.

`/v1/dev/codec/text`

The text codec converts between Prolog textual values and byte lists. It backs the string_bytes/3 predicate for encodings such as text, utf8, octet, and hex.

Field	Value
Path	`/v1/dev/codec/text`
Request	`encode` or `decode`, followed by a Prolog payload term
Response	`ok(Value)` or `error(Code)`
Recommended predicate	`string_bytes/3`

`/v1/dev/crypto/<algorithm>`

Crypto paths expose hashing and signature verification supported by the AXONE blockchain.

Field	Value
Path	`/v1/dev/crypto/<algorithm>`
Open mode	`read_write`
Stream type	Binary for hashes, text for signature verification
Request	Hash devices receive raw bytes. Signature devices receive `verify <pubkey_hex> <data_hex> <signature_hex>`.
Response	Hash devices return raw digest bytes. Signature devices return a Prolog term such as `ok(true)`, `ok(false)`, or `error(Code)`.
Recommended predicates	`crypto_data_hash/3`, `eddsa_verify/4`, `ecdsa_verify/4` from `/v1/lib/crypto.pl`

`/v1/dev/crypto/md5`

Field	Value
Path	`/v1/dev/crypto/md5`
Operation	MD5 digest
Stream type	Binary
Request	Raw bytes
Response	Raw digest bytes
Recommended predicate	`crypto_data_hash/3` with `algorithm(md5)`

`/v1/dev/crypto/sha256`

Field	Value
Path	`/v1/dev/crypto/sha256`
Operation	SHA-256 digest
Stream type	Binary
Request	Raw bytes
Response	Raw digest bytes
Recommended predicate	`crypto_data_hash/3` with `algorithm(sha256)`

`/v1/dev/crypto/sha512`

Field	Value
Path	`/v1/dev/crypto/sha512`
Operation	SHA-512 digest
Stream type	Binary
Request	Raw bytes
Response	Raw digest bytes
Recommended predicate	`crypto_data_hash/3` with `algorithm(sha512)`

`/v1/dev/crypto/ed25519`

Field	Value
Path	`/v1/dev/crypto/ed25519`
Operation	Ed25519 signature verification
Stream type	Text
Request	`verify <pubkey_hex> <data_hex> <signature_hex>`
Response	`ok(true)`, `ok(false)`, or `error(Code)`
Recommended predicate	`eddsa_verify/4` with `type(ed25519)`

`/v1/dev/crypto/secp256r1`

Field	Value
Path	`/v1/dev/crypto/secp256r1`
Operation	ECDSA secp256r1 signature verification
Stream type	Text
Request	`verify <pubkey_hex> <data_hex> <signature_hex>`
Response	`ok(true)`, `ok(false)`, or `error(Code)`
Recommended predicate	`ecdsa_verify/4` with `type(secp256r1)`

`/v1/dev/crypto/secp256k1`

Field	Value
Path	`/v1/dev/crypto/secp256k1`
Operation	ECDSA secp256k1 signature verification
Stream type	Text
Request	`verify <pubkey_hex> <data_hex> <signature_hex>`
Response	`ok(true)`, `ok(false)`, or `error(Code)`
Recommended predicate	`ecdsa_verify/4` with `type(secp256k1)`

`/v1/dev/wasm/<contract_address>/query`

The CosmWasm query path executes a smart query against a contract address visible from the AXONE blockchain.

Field	Value
Path	`/v1/dev/wasm/<contract_address>/query`
Open mode	`read_write`
Stream type	Binary
Request	Raw query bytes, typically UTF-8 JSON
Response	Raw contract response bytes
Recommended predicate	`wasm_query/3` from `/v1/lib/wasm.pl`

This device is query-only. It does not execute transactions or mutate contract state.

/v1​

/v1/lib/*.pl​

/v1/run/header​

/v1/run/comet​

/v1/run/source/files​

/v1/var/lib/bank/<address>​

/v1/var/lib/staking/<delegator>​

/v1/var/lib/staking/validators/<status>/@​

/v1/var/lib/staking/params/@​

/v1/var/lib/logic/users/<publisher>/programs/<program_id>.pl​

/v1/dev/codec/<codec>​

/v1/dev/codec/bech32​

/v1/dev/codec/json​

/v1/dev/codec/text​

/v1/dev/crypto/<algorithm>​

/v1/dev/crypto/md5​

/v1/dev/crypto/sha256​

/v1/dev/crypto/sha512​

/v1/dev/crypto/ed25519​

/v1/dev/crypto/secp256r1​

/v1/dev/crypto/secp256k1​

/v1/dev/wasm/<contract_address>/query​