Armchain API

Beyond the standard Ethereum JSON-RPC methods, Armchain provides additional API namespaces for querying DAG data, epoch information, and validator state. These are useful when you need to interact with Armchain's consensus layer directly.

arm Namespace

The arm namespace provides Armchain-specific methods. These are available when arm is enabled in --http.api.

arm_getBalance

Returns the balance at a given address (alias for eth_getBalance).

curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"arm_getBalance","params":["0xADDRESS","latest"],"id":1}'

arm_getTransactionCount

Returns the transaction count (nonce) for an address.

curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"arm_getTransactionCount","params":["0xADDRESS","latest"],"id":1}'

arm_sendTransaction

Send a transaction (account must be unlocked on the node).

curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"arm_sendTransaction",
    "params":[{
      "from": "0xFROM",
      "to": "0xTO",
      "value": "0xDE0B6B3A7640000"
    }],
    "id":1
  }'

---

dag Namespace

The dag namespace provides access to the DAG (Directed Acyclic Graph) data structures that underpin Lachesis consensus.

dag_getEvent

Returns a DAG event by its hash.

Parameters:

1. eventHash: 32-byte event hash

curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"dag_getEvent","params":["0xEVENT_HASH"],"id":1}'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "hash": "0x...",
    "creator": 1,
    "epoch": 42,
    "seq": 1057,
    "frame": 100,
    "isRoot": false,
    "parents": ["0xPARENT_1", "0xPARENT_2"],
    "gasPowerLeft": { "shortTerm": 1000000, "longTerm": 5000000 },
    "gasPowerUsed": 28000,
    "txHash": "0x...",
    "lamportTime": 50000,
    "creationTime": 1708300000000000000
  }
}

dag_getEventsByEpoch

Returns events in a specific epoch.

Parameters:

1. epoch: Epoch number

curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"dag_getEventsByEpoch","params":["0x2A"],"id":1}'

dag_getEpochStats

Returns statistics for the current or specified epoch.

Parameters:

1. epoch: (optional) Epoch number. Defaults to current epoch.

curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"dag_getEpochStats","params":[],"id":1}'

dag_getHeads

Returns the current head events in the DAG (latest events from each validator).

curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"dag_getHeads","params":[],"id":1}'

---

aBFT Information

abft_getValidators

Returns the current validator set.

curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"abft_getValidators","params":[],"id":1}'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "epoch": 42,
    "validators": [
      {
        "id": 1,
        "pubkey": "0x01...",
        "stake": "1000000000000000000000000",
        "address": "0x..."
      }
    ]
  }
}

abft_getDowntime

Returns downtime information for a validator.

Parameters:

1. validatorId: Validator ID

curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"abft_getDowntime","params":[1],"id":1}'

abft_getEpoch

Returns the current epoch number.

curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"abft_getEpoch","params":[],"id":1}'

---

debug Namespace

debug_traceTransaction

Replays a transaction and returns execution traces.

Parameters:

1. txHash: Transaction hash

2. options: (optional) Tracing options

curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"debug_traceTransaction",
    "params":["0xTX_HASH", {"tracer": "callTracer"}],
    "id":1
  }'

debug_traceCall

Traces a call without executing it on-chain.

curl -X POST http://localhost:4000 -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "method":"debug_traceCall",
    "params":[{
      "from": "0xFROM",
      "to": "0xTO",
      "data": "0xCALLDATA"
    }, "latest", {"tracer": "callTracer"}],
    "id":1
  }'

---

Transaction Object Fields (Type 3)

When querying Type 3 PQC transactions, the response includes these fields:

Field	Type	Description
type	string	"0x3" - PQC transaction type
hash	string	Transaction hash
from	string	Sender address (derived from ML-DSA44 public key)
to	string	Recipient address (or null for contract creation)
value	string	Transfer value in wei
nonce	string	Sender nonce
gas / gasLimit	string	Gas limit
maxFeePerGas	string	Maximum total fee per gas
maxPriorityFeePerGas	string	Priority fee per gas
input / data	string	Transaction input data
chainId	string	Chain ID
blockNumber	string	Block number (when mined)
blockHash	string	Block hash (when mined)
transactionIndex	string	Index in block

Note: Type 3 transactions do not have v, r, s fields. Signature data is in the signatureBlob field.

---

Enabling API Namespaces

# Enable specific namespaces
./build/armnode \
  --http \
  --http.api eth,net,web3,arm,dag,txpool,debug,admin,personal \
  --ws \
  --ws.api eth,net,web3,arm,dag

Security: Only enable personal, admin, and debug on trusted/local networks.

Further Reading

• JSON-RPC Standard Methods: Standard Ethereum RPC methods

• DAG Structure: Understanding DAG events

• Consensus: Lachesis aBFT and epochs

• Fakenet: Local development network setup