RPC API

Overview

Ashen exposes a JSON-RPC 2.0 API defined by a single IDL (Interface Definition Language) file: node_rpc_v1.idl. Every type, method, parameter, and return value in the API is declared in this IDL. Clients, the TUI, and code-generation tooling all derive their behavior from the same source of truth rather than hand-coded stubs.

IDL Discovery

The node serves the IDL itself over HTTP so that tools can discover the API at runtime.

Endpoint	Returns	Description
GET /v2/rpc/idl	text/plain	Raw IDL source text
GET /v2/rpc/manifest	application/json	Parsed manifest with method signatures, struct/enum definitions

CLI shortcuts:

just rpc-idl        # fetch raw IDL from a running node
just rpc-manifest   # fetch the JSON manifest

TUI Explorer

The built-in TUI embeds the IDL at compile time and provides an RPC Explorer screen. It parses node_rpc_v1.idl at startup — no network call is needed for method discovery.

Features:

• Filterable method list (press / to search)
• Method signatures with parameter types and documentation
• Direct execution: press x to call a method, v for read-only view
• On-chain contract IDL loading via contract_idl()

Protocol

All RPC calls use JSON-RPC 2.0 over HTTP:

POST /v2/rpc
Content-Type: application/json

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "NodeRpcV1.status",
  "params": {}
}

Methods can be addressed by qualified name (NodeRpcV1.status) or unqualified (status) when unambiguous.

Type Conventions

• Enums are encoded as {"type": "<variant_snake_case>", "value": <payload>}. Example: {"type": "transfer", "value": {"to": "0x...", "amount": "10"}}.
• Large integers (u128, i128) are JSON strings: "1000000000000000000".
• Addresses are hex strings with 0x prefix.
• Hashes are lowercase hex strings (no fixed 0x requirement).

Access Tiers

Methods are classified into three access tiers:

Tier	Description	Examples
Public	Open to all callers, no auth required	status, health, account, tx_submit
Paid (x402)	Expensive operations, may require payment or rate limiting	tx_simulate, chain_traceCall, view_call
Admin	Restricted to node operators	tx_build, import_snapshot_chunk

Authentication uses a Bearer token in the Authorization header when required.

Method Reference

Status & Health

Method	Parameters	Returns	Description
status	—	Status	Chain tip, finalized height, epoch, validator set, txpool size
health	—	HealthResult	Liveness probe (Kubernetes-compatible)
readiness	—	ReadinessResult	Readiness probe: sync status, epoch key availability
validator_status	—	ValidatorStatus	DKG state, sync, peer health, consensus metrics

Accounts & Contracts

Method	Parameters	Returns	Description
account	address	Account	Balance and nonce lanes for an address
accounts	addresses[]	AccountsResult	Batch account lookup (deterministic order)
predict_address	deployer, offset?	PredictAddressResult	Predict a contract deploy address
contract_metadata	address	ContractMetadataResult	VM type, code hash, ABI version, upgrade policy
contract_idl	address	ContractIdlResult	Raw IDL text stored on-chain (if deployed with IDL)
view_call	ViewCallArgs	ViewCallResult	Read-only contract call (no state change)

Transaction Building & Submission

Method	Parameters	Returns	Description
tx_build	TxBuildArgs	TxBuildResult	Build an unsigned transaction envelope
tx_build_simulate	TxBuildArgs	TxBuildSimulateResult	Build + simulate in one call
tx_submit	TxSubmitArgs	TxSubmitResult	Submit a signed transaction
tx_by_hash	tx_hash	TxByHashResult	Look up transaction by hash (pending, included, or not found)
tx_receipt	tx_hash	TxReceiptResult	Full receipt with decoded events (when IDL is available)

Simulation & Tracing

Method	Parameters	Returns	Description
tx_simulate	TxSimulateArgs	TxSimulateResult	Simulate execution, estimate gas
tx_simulate_access	TxSimulateAccessArgs	TxSimulateAccessResult	Simulate + return storage access list
tx_simulate_trace	TxSimulateTraceArgs	TxSimulateTraceResult	Simulate with full execution trace
tx_simulate_pipeline	TxSimulatePipelineArgs	TxSimulatePipelineResult	Multi-step pipeline (txs + view calls)
chain_traceTransaction	ChainTraceTransactionArgs	ChainTraceTransactionResult	Trace an already-included transaction
chain_traceCall	ChainTraceCallArgs	ChainTraceCallResult	Trace a view call

Blocks & Listings

Method	Parameters	Returns	Description
list_blocks	ListBlocksArgs	ListBlocksResult	Paginated blocks (newest-first, cursor-based)
list_txs	ListTxsArgs	ListTxsResult	Paginated transactions (newest-first)
list_txs_by_sender	ListTxsBySenderArgs	ListTxsBySenderResult	Transactions by sender address
list_txs_by_contract	ListTxsByContractArgs	ListTxsByContractResult	Transactions involving a contract
get_logs	GetLogsArgs	GetLogsResult	Event logs by contract, topic, and/or block range
list_pending_txs	ListPendingTxsArgs	ListPendingTxsResult	Pending transactions from the mempool
txpool_stats	—	TxpoolStats	Mempool size, lanes, sealed queue
get_blocks	GetBlocksArgs	GetBlocksResult	Blocks by height range
get_block_summaries	GetBlocksArgs	GetBlockSummariesResult	Lightweight block summaries for a height range
get_txs_in_range	GetBlocksArgs	GetTxsInRangeResult	All transactions in a block height range
get_checkpoint_list	—	CheckpointListResult	Available checkpoints

Proofs & Light Client

Method	Parameters	Returns	Description
finality_proof	FinalityProofArgs	FinalityProofResult	Finality proof for a block height
light_client_context	LightClientContextArgs	LightClientContextResult	Verification context for light clients
state_proof	StateProofArgs	StateProofResult	State proof for a contract (optionally a specific slot)
finalized_history_root	FinalizedHistoryRootArgs	FinalizedHistoryRootResult	Current finalized history MMR root
finalized_history_proof	FinalizedHistoryProofArgs	FinalizedHistoryProofResult	MMR membership proof for a finalized block

Snapshots & Sync

Method	Parameters	Returns	Description
get_light_snapshot	GetLightSnapshotArgs	GetLightSnapshotResult	Light snapshot for verified fast sync
get_checkpoint	GetCheckpointArgs	GetCheckpointResult	Checkpoint descriptor by height
list_checkpoints	ListCheckpointsArgs	ListCheckpointsResult	Available checkpoints with archive descriptors
get_snapshot_chunk	GetSnapshotChunkArgs	GetSnapshotChunkResult	Chunk of snapshot entries for state sync
import_snapshot_chunk	ImportSnapshotChunkArgs	ImportSnapshotChunkResult	Import snapshot entries (Admin)

Private Mempool & Bundles

Method	Parameters	Returns	Description
tx_submit_sealed	TxSubmitSealedArgs	TxSubmitSealedResult	Submit a threshold-encrypted transaction
get_epoch_key	GetEpochKeyArgs	GetEpochKeyResult	Threshold encryption public key for sealing
tx_submit_bundle	TxSubmitBundleArgs	TxSubmitBundleResult	Submit an atomic transaction bundle
chain_simulateBundle	BundleSimulateArgs	BundleSimulateResult	Simulate a bundle with dependency analysis

Contract IDL

Contracts can store their IDL on-chain at deploy time. The contract_idl method retrieves the raw IDL text for any address. The TUI uses this to provide method-level exploration and parameter templates for contract calls — the same IDL-driven discovery that powers the node RPC explorer also works for individual contracts.

Example

curl -s http://localhost:8080/v2/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "NodeRpcV1.status",
    "params": {}
  }' | jq .result

{
  "version": "0.1.0",
  "chain_id": 1,
  "now_ms": 1706900000000,
  "uptime_ms": 3600000,
  "block_time_ms": 500,
  "tip": {
    "height": 12345,
    "hash": "a1b2c3...",
    "timestamp_ms": 1706899999500,
    "state_root": "d4e5f6...",
    "epoch": 42,
    "view": 0
  },
  "finalized_height": 12340,
  "latest_checkpoint": {
    "height": 12300,
    "state_root": "..."
  },
  "txpool_size": 7
}