API References
GenLayer Node API

GenLayer Node API

The GenLayer Node provides a JSON-RPC API (opens in a new tab) for interacting with it. This API allows you to execute contract calls, retrieve transaction information, and perform various blockchain operations.

GenLayer Methods

gen_call

Executes a new message call immediately without creating a transaction on the blockchain. This method supports read operations, write operations, and contract deployments.

Method: gen_call

Parameters:

  • request (object, required): The contract call request parameters
    • from (string, required): The address making the call
    • to (string, required): The contract address to call
    • Data (string, required): The encoded function call data
    • Type (string, required): The type of call ("read", "write", or "deploy")
    • blockNumber (string, optional): The block number to query at (hex-encoded). If not provided, uses latest block
    • status (string, optional): The transaction status filter ("finalized" or "accepted"). If not provided, uses accepted state
    • value (string, optional): The value to send with the call (hex-encoded)

Returns: Hex-encoded result data

Example - Read Call (Latest Accepted State):

{
  "jsonrpc": "2.0",
  "method": "gen_call",
  "params": [
    {
      "Type": "read",
      "Data": "0xd8960e066d6574686f646c6765745f686176655f636f696e00",
      "from": "0xf6A60752C24Cd3BFcAf8d387a5EB62d3746F44EE",
      "to": "0xCe5712E63fd5475288aB1B7c0a368B9417357b81",
      "gas": "0x5208",
      "value": "0x0"
    }
  ],
  "id": 1
}

Example - Read Call with Specific Block and Status:

{
  "jsonrpc": "2.0",
  "method": "gen_call",
  "params": [
    {
      "Type": "read",
      "Data": "0xd8960e066d6574686f646c6765745f686176655f636f696e00",
      "from": "0xf6A60752C24Cd3BFcAf8d387a5EB62d3746F44EE",
      "to": "0xCe5712E63fd5475288aB1B7c0a368B9417357b81",
      "blockNumber": "0x151ec5",
      "status": "accepted"
    }
  ],
  "id": 1
}

Example - Write Call:

{
  "jsonrpc": "2.0",
  "method": "gen_call",
  "params": [
    {
      "from": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6",
      "to":   "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6",
      "data": "0xa9059cbb000000000000000000000000742d35cc6634c0532925a3b8d4c9db96c4b4d8b6",
      "type": "write",
      "gas":  "0x5208",
      "value":"0x0"
    }
  ],
  "id": 1
}

Notes:

  • The blockNumber parameter can be either hex-encoded with a 0x prefix (e.g., "0x151ec5") or decimal (e.g., "1384133")
  • Valid status values are "accepted" (default) and "finalized"
  • When both parameters are omitted, the call executes against the latest accepted state
  • For read and write type calls, if the contract doesn't exist at the specified block/status combination, an error will be returned
  • For deploy type calls, the status and blockNumber parameters are not used for contract state validation since no contract exists yet

gen_getContractSchema

Retrieve the schema/interface of a GenLayer contract to understand its available methods and properties.

Method: gen_getContractSchema

Parameters:

  • request (object, required): The contract schema request
    • code (string, required): Base64-encoded contract code

Returns: Contract schema object with methods and properties

{
  "ctor": { // constructor info
    "kwparams": {}, // dict
    "params": [["value", "type"]] // list of tuples
  },
  "methods": { // dict from method name to method info
    "method_name": {
      "kwparams": {}, // dict
      "params": [["value", "type"]], // list of tuples
      "payable": false, // bool
      "readonly": false, // bool
      "ret": "null" // string
    },
  }
}

Example:

{
  "jsonrpc": "2.0",
  "method": "gen_getContractSchema",
  "params": [
    {
      "code": "IyB7ICJEZXBlbmRzIjogInB5LWdlbmxheWVyOnRlc3QiIH0KCmZyb20gZ2VubGF5ZXIgaW1wb3J0ICoKCgojIGNvbnRyYWN0IGNsYXNzCmNsYXNzIFN0b3JhZ2UoZ2wuQ29udHJhY3QpOgogICAgc3RvcmFnZTogc3RyCgogICAgIyBjb25zdHJ1Y3RvcgogICAgZGVmIF9faW5pdF9fKHNlbGYsIGluaXRpYWxfc3RvcmFnZTogc3RyKToKICAgICAgICBzZWxmLnN0b3JhZ2UgPSBpbml0aWFsX3N0b3JhZ2UKCiAgICAjIHJlYWQgbWV0aG9kcyBtdXN0IGJlIGFubm90YXRlZCB3aXRoIHZpZXcKICAgIEBnbC5wdWJsaWMudmlldwogICAgZGVmIGdldF9zdG9yYWdlKHNlbGYpIC0+IHN0cjoKICAgICAgICByZXR1cm4gc2VsZi5zdG9yYWdlCgogICAgIyB3cml0ZSBtZXRob2QKICAgIEBnbC5wdWJsaWMud3JpdGUKICAgIGRlZiB1cGRhdGVfc3RvcmFnZShzZWxmLCBuZXdfc3RvcmFnZTogc3RyKSAtPiBOb25lOgogICAgICAgIHNlbGYuc3RvcmFnZSA9IG5ld19zdG9yYWdlCg=="
    }
  ],
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "ctor": {
      "kwparams": {},
      "params": [["initial_storage", "string"]]
    },
    "methods": {
      "get_storage": {
        "kwparams": {},
        "params": [],
        "readonly": true,
        "ret": "string"
      },
      "update_storage": {
        "kwparams": {},
        "params": [["new_storage", "string"]],
        "payable": false,
        "readonly": false,
        "ret": "null"
      }
    }
  },
  "id": 1
}

gen_getTransactionReceipt

Retrieves the transaction receipt for a given transaction ID. This endpoint is a proxy to the underlying consensus layer's getTransactionAllData function, providing detailed information about a transaction that has been processed.

Method: gen_getTransactionReceipt

Parameters:

  • request (object, required):
    • txId (string, required): The 32-byte transaction hash as a hexadecimal string with a 0x prefix.

Returns:

A Transaction object which contains the details of the transaction. The structure is based on ITransactionsTransaction from the consensus contracts. The object has the following fields:

  • id (string): The transaction ID as a hex string.
  • txOrigin (address): The original address that initiated the transaction.
  • sender (address): The address of the sender.
  • recipient (address): The destination address of the transaction.
  • activator (address): The address of the validator that activated the transaction.
  • status (uint8): The current status of the transaction.
  • previousStatus (uint8): The previous status of the transaction.
  • txSlot (uint256): The transaction slot number.
  • initialRotations (uint256): The initial number of rotations.
  • numOfInitialValidators (uint256): The number of initial validators.
  • randomSeed (string): The random seed used for the transaction as a hex string.
  • txExecutionHash (string): The execution hash of the transaction as a hex string.
  • otherExecutionFieldsHash (string): Hash of other execution fields as a hex string.
  • txData (string): The transaction data as a hex string.
  • eqBlocksOutputs (string): The equivalent blocks outputs as a hex string.
  • timestamps (object): Object containing various timestamps:
    • Created (uint256): When the transaction was created.
    • Pending (uint256): When the transaction became pending.
    • Activated (uint256): When the transaction was activated.
    • Proposed (uint256): When the transaction was proposed.
    • Committed (uint256): When the transaction was committed.
    • LastVote (uint256): When the last vote was cast.
    • AppealSubmitted (uint256): When an appeal was submitted.
    • LeaderRevealed (uint256): When the leader was revealed.
  • result (uint256): The result of the transaction execution.
  • readStateBlockRange (object): Block range information:
    • ActivationBlock (uint256): The activation block number.
    • ProcessingBlock (uint256): The processing block number.
    • ProposalBlock (uint256): The proposal block number.
  • consumedValidators (array): Array of validator addresses that participated.
  • roundData (array): Array of round data objects containing:
    • round (uint256): The round number.
    • leaderIndex (uint256): Index of the round leader.
    • votesCommitted (uint256): Number of votes committed.
    • votesRevealed (uint256): Number of votes revealed.
    • appealBond (uint256): The appeal bond amount.
    • rotationsLeft (uint256): Number of rotations remaining.
    • result (uint256): The round result.
    • roundValidators (array): Array of validator addresses for this round.
    • validatorVotes (string): Base64-encoded validator votes.
    • validatorVotesHash (array): Array of vote hashes as hex strings.
    • validatorResultHash (array): Array of result hashes as hex strings.

Example Request:

{
  "jsonrpc": "2.0",
  "method": "gen_getTransactionReceipt",
  "params": [
    {
      "txId": "0x635060dd514082096d18c8eb64682cc6a944f9ce1ae6982febf7a71e9f656f49"
    }
  ],
  "id": 1
}

Example Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "0x635060dd514082096d18c8eb64682cc6a944f9ce1ae6982febf7a71e9f656f49",
    "txOrigin": "0x5b70759760a85d92bf972b67ee8558e8e8da87d4",
    "sender": "0x5b70759760a85d92bf972b67ee8558e8e8da87d4",
    "recipient": "0x73ca5a2b51edf506ceaf110a41780ec51294d89f",
    "activator": "0xf27b07d36ff5b9dcd37fd3a09811d6456dd4483a",
    "status": 14,
    "previousStatus": 0,
    "txSlot": 1,
    "initialRotations": 1,
    "numOfInitialValidators": 5,
    "randomSeed": "0x3d0bdff63bce1cf84b155f1557bb15e303b903b1b559325b6492794a5e498954",
    "txExecutionHash": "0x76744dc491b1725eb2ba08cf516855c14aac310e36711368c04442fd39d61853",
    "otherExecutionFieldsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "txData": "f5b31604617267730da4017570646174656420746573742073746f72616765066d6574686f64747570646174655f73746f7261676500",
    "eqBlocksOutputs": "c0",
    "timestamps": {
      "Created": 1750774777,
      "Pending": 1750774777,
      "Activated": 1750774781,
      "Proposed": 1750774786,
      "Committed": 1750774791,
      "LastVote": 0,
      "AppealSubmitted": 0,
      "LeaderRevealed": 0
    },
    "result": 0,
    "readStateBlockRange": {
      "ActivationBlock": 1377797,
      "ProcessingBlock": 1377797,
      "ProposalBlock": 1377798
    },
    "consumedValidators": [
      "0xa707a1d9dd946242f921f0ad62f61e1b7df30c85",
      "0xf27b07d36ff5b9dcd37fd3a09811d6456dd4483a",
      "0xf3738216c3208d77a9db79a1d31824e5133083c4",
      "0x56394354538bff1e0ee5021c2b6d3522fce30257",
      "0xcfdbac032f82f388d9eca76efa6610b98e7f59fe"
    ],
    "roundData": [
      {
        "round": 0,
        "leaderIndex": 3,
        "votesCommitted": 5,
        "votesRevealed": 0,
        "appealBond": 0,
        "rotationsLeft": 1,
        "result": 0,
        "roundValidators": [
          "0xa707a1d9dd946242f921f0ad62f61e1b7df30c85",
          "0xf27b07d36ff5b9dcd37fd3a09811d6456dd4483a",
          "0xf3738216c3208d77a9db79a1d31824e5133083c4",
          "0x56394354538bff1e0ee5021c2b6d3522fce30257",
          "0xcfdbac032f82f388d9eca76efa6610b98e7f59fe"
        ],
        "validatorVotes": "AAAAAAA=",
        "validatorVotesHash": [
          "54e3478b02dfb009a35d46b19ac7c967b65416430a33d3860e9301a0f2b19d57",
          "f74a48e7283c91757bf2c612e40f8a9eb69ea0f02cf5e6b89c3c9b6ad629a3c1",
          "2f51c3b1d9ff35140260fb42330fbed12303a9915b8da786c9b8ed060983fa6c",
          "730127e27167fcf2450fe506250b85d916fbf07dd874b7f0c69a2f8ceb9e44a6",
          "473d57953f7e7c1a6fb1d2335618f21088025e02bd9fa30d6f85f20a55c24d15"
        ],
        "validatorResultHash": [
          "0000000000000000000000000000000000000000000000000000000000000000",
          "0000000000000000000000000000000000000000000000000000000000000000",
          "0000000000000000000000000000000000000000000000000000000000000000",
          "0000000000000000000000000000000000000000000000000000000000000000",
          "0000000000000000000000000000000000000000000000000000000000000000"
        ]
      }
    ]
  }
}

gen_getContractState

Retrieves the current state of a GenLayer intelligent contract at a specific block height and transaction status.

Method: gen_getContractState

Parameters:

  • request (object, required): The contract state request parameters
    • address (string, required): The contract address to query
    • blockNumber (string, optional): The block number to query at (hex-encoded). If not provided, uses latest block
    • status (string, optional): The transaction status filter ("finalized" or "accepted"). If not provided, uses accepted state

Returns: Hex-encoded contract state data

Example Request - Latest Accepted State:

{
  "jsonrpc": "2.0",
  "method": "gen_getContractState",
  "params": [
    {
      "address": "0x73ca5a2b51edf506ceaf110a41780ec51294d89f"
    }
  ],
  "id": 1
}

Example Request - Specific Block and Status:

{
  "jsonrpc": "2.0",
  "method": "gen_getContractState",
  "params": [
    {
      "address": "0x73ca5a2b51edf506ceaf110a41780ec51294d89f",
      "blockNumber": "0x151ec5",
      "status": "accepted"
    }
  ],
  "id": 1
}

Example Response:

{
  "jsonrpc": "2.0",
  "result": "0xd9960e0773746f726167656c6e757064617465642074657374207374",
  "id": 1
}

Notes:

  • The blockNumber parameter should be hex-encoded with a 0x prefix
  • Valid status values are "accepted" (default) and "finalized"
  • The returned state is hex-encoded binary data with a 0x prefix
  • Empty contract state returns "0x"
  • If the contract doesn't exist at the specified block/status, an error will be returned

cURL Example:

# Get latest accepted state
curl -X POST http://localhost:9151 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "gen_getContractState",
    "params": [{
      "address": "0x73ca5a2b51edf506ceaf110a41780ec51294d89f"
    }],
    "id": 1
  }'
 
# Get state at specific block with accepted status
curl -X POST http://localhost:9151 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "gen_getContractState",
    "params": [{
      "address": "0x73ca5a2b51edf506ceaf110a41780ec51294d89f",
      "blockNumber": "0x151ec5",
      "status": "accepted"
    }],
    "id": 1
  }'

Debug Methods

These methods are available for debugging and testing purposes during development.

gen_dbg_ping

Simple connectivity test method that returns a "pong" response.

Method: gen_dbg_ping

Parameters: None

Returns: "pong" string

Example:

{
  "jsonrpc": "2.0",
  "method": "gen_dbg_ping",
  "params": [],
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": "pong",
  "id": 1
}

gen_dbg_trie

Get trie information for debugging node internal DB state.

Method: gen_dbg_trie

Parameters:

  • request (object, required): The trie debug request
    • txID (string, required): Transaction ID (hex-encoded)
    • round (integer, required): Round number

Returns: Trie debug information string

Example:

{
  "jsonrpc": "2.0",
  "method": "gen_dbg_trie",
  "params": [
    {
      "txID": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6742d35Cc6634C0532925a3b8",
      "round": 0
    }
  ],
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": "graph TD\nnode0@{label: \"br  seq=1\"}\nnode1@{label: \"ext seq=1 0x00000000000000000000000000000000000000000000000000000000000000000000000\"}\nnode1 --\u003e data2@{label: \"seq=1\n[21 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]\"}\nnode0 --\u003e|0| node1\nnode3@{label: \"ext seq=1 0x72d46c3ada9f897c74d349bbfe0e450c798167c9f580f8daf85def57e96c3ea00000000\"}\nnode3 --\u003e data4@{label: \"seq=1\n[105 110 105 116 105 97 108 32 115 116 111 114 97 103 101 32 118 97 108 117 101 0 0 0 0 0 0 0 0 0 0 0]\"}\nnode0 --\u003e|3| node3\n",
  "id": 1
}
 
## Ethereum Compatibility
 
The GenLayer Node also supports Ethereum-compatible methods that are proxied to the underlying infrastructure. These methods follow the standard [Ethereum JSON-RPC specification](https://ethereum.org/en/developers/docs/apis/json-rpc/) and are prefixed with `eth_`.
 
**Examples of supported Ethereum methods:**
 
- `eth_blockNumber`
- `eth_getBalance`
- `eth_sendTransaction`
- `eth_call`
- And other standard Ethereum JSON-RPC methods
 
## zkSync Compatibility
 
[zkSync-compatible](https://docs.zksync.io/zksync-protocol/api/zks-rpc) methods are also supported and proxied to the underlying infrastructure. These methods are prefixed with `zksync_`.
 
## Usage Examples
 
### cURL
 
```bash
# Test connectivity
curl -X POST http://localhost:9151 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "gen_dbg_ping",
    "params": [],
    "id": 1
  }'
 
# Execute a contract call
curl -X POST http://localhost:9151 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "gen_call",
    "params": [{
      "from": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6",
      "to": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6",
      "data": "0x70a08231000000000000000000000000742d35cc6634c0532925a3b8d4c9db96c4b4d8b6",
      "type": "read",
      "transaction_hash_variant": "latest-nonfinal"
    }],
    "id": 1
  }'
 
# Get contract schema
curl -X POST http://localhost:9151 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "gen_getContractSchema",
    "params": [{
      "code": "IyB7ICJEZXBlbmRzIjogInB5LWdlbmxheWVyOnRlc3QiIH0KCmZyb20gZ2VubGF5ZXIgaW1wb3J0ICoKCgojIGNvbnRyYWN0IGNsYXNzCmNsYXNzIFN0b3JhZ2UoZ2wuQ29udHJhY3QpOgogICAgc3RvcmFnZTogc3RyCgogICAgIyBjb25zdHJ1Y3RvcgogICAgZGVmIF9faW5pdF9fKHNlbGYsIGluaXRpYWxfc3RvcmFnZTogc3RyKToKICAgICAgICBzZWxmLnN0b3JhZ2UgPSBpbml0aWFsX3N0b3JhZ2UKCiAgICAjIHJlYWQgbWV0aG9kcyBtdXN0IGJlIGFubm90YXRlZCB3aXRoIHZpZXcKICAgIEBnbC5wdWJsaWMudmlldwogICAgZGVmIGdldF9zdG9yYWdlKHNlbGYpIC0+IHN0cjoKICAgICAgICByZXR1cm4gc2VsZi5zdG9yYWdlCgogICAgIyB3cml0ZSBtZXRob2QKICAgIEBnbC5wdWJsaWMud3JpdGUKICAgIGRlZiB1cGRhdGVfc3RvcmFnZShzZWxmLCBuZXdfc3RvcmFnZTogc3RyKSAtPiBOb25lOgogICAgICAgIHNlbGYuc3RvcmFnZSA9IG5ld19zdG9yYWdlCg=="
    }],
    "id": 1
  }'
 
# Get debug trie information
curl -X POST http://localhost:9151 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "gen_dbg_trie",
    "params": [{
      "txID": "0x742d35Cc6634C0532925a3b8D4C9db96c4b4d8b6742d35Cc6634C0532925a3b8",
      "round": 0
    }],
    "id": 1
  }'
 
# Get transaction receipt
curl -X POST http://localhost:9151 \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "gen_getTransactionReceipt",
    "params": [{
      "txId": "0x635060dd514082096d18c8eb64682cc6a944f9ce1ae6982febf7a71e9f656f49"
    }],
    "id": 1
  }'

Ops Methods

These methods provide operational endpoints for monitoring the GenLayer node.

balance

Returns the configured validator's account balance in multiple formats including hexadecimal, wei, and GEN units.

Method: GET /balance

Parameters: None

Returns: JSON object containing the validator's balance in three formats

Example Request:

curl -X GET http://localhost:9153/balance

Example Response:

{
  "balance_hex": "0x0de0b6b3a7640000",
  "balance_wei": "1000000000000000000",
  "balance_gen": "1.000"
}

Response Fields:

  • balance_hex (string): The balance encoded as hexadecimal with "0x" prefix
  • balance_wei (string): The balance in wei as a decimal string
  • balance_gen (string): The balance in GEN units formatted with 3 decimal places

Notes:

  • This endpoint is only available when the node is running in validator mode
  • The balance is always retrieved from the latest block
  • The validator address is configured at node startup
  • If the validator address is not configured, the zero address (0x0000...0000) is used
  • Balance conversions: 1 GEN = 1,000,000,000,000,000,000 wei (10^18 wei)
  • Returns HTTP 503 if the node is not in validator mode
  • Returns HTTP 500 if there's an error retrieving the balance

Example Response (Zero Balance):

{
  "balance_hex": "0x",
  "balance_wei": "0",
  "balance_gen": "0.000"
}

Example Response (Large Balance):

{
  "balance_hex": "0x3635c9adc5dea00000",
  "balance_wei": "1000000000000000000000",
  "balance_gen": "1000.000"
}

Error Response (Not in Validator Mode):

{
  "message": "Balance endpoint not available in rollup mode"
}

cURL Example with Headers:

curl -X GET http://localhost:9153/balance \
  -H "Accept: application/json" \
  -v

health

Returns the health status of the GenLayer node along with version information and the status of individual health checks.

Method: GET /health

Parameters: None

Returns: JSON object containing the overall health status, version information, and individual check results

Example Request:

curl -X GET http://localhost:9153/health

Example Response:

{
  "status": "up",
  "node_version": "v1.2.3",
  "protocol_version": "consensus-v2.1",
  "checks": {
    "test-check": {
      "status": "up",
      "timestamp": "2024-01-15T10:30:45Z"
    }
  }
}

Response Fields:

  • status (string): Overall health status - "up" if all checks pass, "down" if any check fails
  • node_version (string): The version of the GenLayer node software
  • protocol_version (string): The consensus protocol version
  • checks (object, optional): Map of individual health check results
    • [check-name] (object): Results for a specific health check
      • status (string): Check status - "up" or "down"
      • timestamp (string): ISO 8601 timestamp of when the check was performed
      • error (string, optional): Error message if check failed

HTTP Status Codes:

  • 200 OK: Node is healthy (all checks passing)
  • 503 Service Unavailable: Node is unhealthy (one or more checks failing)

Notes:

  • The endpoint has a 5-second timeout for all health checks
  • The checks field is only included when health checks are configured
  • Version fields will show "unset" if version information is not available
  • Individual health checks are executed concurrently with results aggregated in the response

Example Response (Unhealthy):

{
  "status": "down",
  "node_version": "v1.2.3",
  "protocol_version": "consensus-v2.1",
  "checks": {
    "database": {
      "status": "down",
      "error": "connection timeout",
      "timestamp": "2024-01-15T10:30:45Z"
    },
    "consensus": {
      "status": "up",
      "timestamp": "2024-01-15T10:30:45Z"
    }
  }
}

cURL Example with Headers:

curl -X GET http://localhost:9153/health \
  -H "Accept: application/json" \
  -v

metrics

Exposes Prometheus-compatible metrics for monitoring node performance and health.

Method: GET /metrics

Parameters: None

Returns: Prometheus-format text response with all collected metrics

Example Request:

curl -X GET http://localhost:9153/metrics

Example Response:

# HELP genlayer_node_cpu_usage_percent Current CPU usage percentage (0-100)
# TYPE genlayer_node_cpu_usage_percent gauge
genlayer_node_cpu_usage_percent{component="node"} 15.5
genlayer_node_cpu_usage_percent{component="genvm-llm"} 45.2
genlayer_node_cpu_usage_percent{component="genvm-web"} 12.8
genlayer_node_cpu_usage_percent{component="webdriver"} 5.3

# HELP genlayer_node_memory_rss_bytes Resident Set Size (RSS) memory usage in bytes
# TYPE genlayer_node_memory_rss_bytes gauge
genlayer_node_memory_rss_bytes{component="node"} 524288000
genlayer_node_memory_rss_bytes{component="genvm-llm"} 2147483648

# HELP genlayer_node_network_rx_bytes_total Total bytes received across all network interfaces
# TYPE genlayer_node_network_rx_bytes_total counter
genlayer_node_network_rx_bytes_total{component="node"} 1073741824

Available Metrics

The node collects metrics for three main components:

  • Node - The main node process
  • GenVM - The GenVM modules (LLM and Web)
  • WebDriver - The WebDriver container

CPU Metrics

genlayer_node_cpu_usage_percent

Current CPU usage percentage (0-100).

Type: Gauge

Labels:

  • component: One of node, genvm-llm, genvm-web, webdriver

Example:

genlayer_node_cpu_usage_percent{component="node"} 15.5
genlayer_node_cpu_usage_percent{component="genvm-llm"} 45.2
genlayer_node_cpu_usage_percent{component="genvm-web"} 12.8
genlayer_node_cpu_usage_percent{component="webdriver"} 5.3

Memory Metrics

genlayer_node_memory_rss_bytes

Resident Set Size (RSS) memory usage in bytes.

Type: Gauge

Labels:

  • component: One of node, genvm-llm, genvm-web, webdriver

Example:

genlayer_node_memory_rss_bytes{component="node"} 524288000
genlayer_node_memory_rss_bytes{component="genvm-llm"} 2147483648

genlayer_node_memory_vms_bytes

Virtual Memory Size (VMS) in bytes.

Type: Gauge

Labels:

  • component: One of node, genvm-llm, genvm-web, webdriver

Note: Only available for node and GenVM components.

genlayer_node_memory_usage_bytes

Current memory usage in bytes (WebDriver only).

Type: Gauge

Labels:

  • component: webdriver

genlayer_node_memory_limit_bytes

Memory limit in bytes (WebDriver only).

Type: Gauge

Labels:

  • component: webdriver

genlayer_node_memory_percent

Memory usage percentage.

Type: Gauge

Labels:

  • component: One of genvm-llm, genvm-web, node, webdriver
  • node: Node address (hex format)

genlayer_node_memory_peak_bytes

Peak memory usage in bytes (GenVM components only).

Type: Gauge

Labels:

  • component: One of genvm-llm, genvm-web
  • node: Node address (hex format)

Network Metrics

genlayer_node_network_rx_bytes_total

Total bytes received across all network interfaces.

Type: Counter

Labels:

  • component: One of node, genvm-llm, genvm-web, webdriver
  • node: Node address (hex format)

Example:

genlayer_node_network_rx_bytes_total{component="node",node="0x84b6cbd007511352d3fea26834c5c39a440903c4"} 96879942
genlayer_node_network_rx_bytes_total{component="webdriver",node="0x84b6cbd007511352d3fea26834c5c39a440903c4"} 84

genlayer_node_network_tx_bytes_total

Total bytes transmitted across all network interfaces.

Type: Counter

Labels:

  • component: One of node, genvm-llm, genvm-web, webdriver
  • node: Node address (hex format)

Disk Metrics

genlayer_node_disk_free_bytes

Available free disk space in bytes.

Type: Gauge

Labels:

  • component: node
  • directory: One of genlayer.db, keystore, logs
  • node: Node address (hex format)

genlayer_node_disk_total_bytes

Total disk space in bytes.

Type: Gauge

Labels:

  • component: node
  • directory: One of genlayer.db, keystore, logs
  • node: Node address (hex format)

genlayer_node_disk_usage_bytes

Used disk space in bytes.

Type: Gauge

Labels:

  • component: node
  • directory: One of genlayer.db, keystore, logs
  • node: Node address (hex format)

genlayer_node_disk_usage_percent

Used disk space as percentage.

Type: Gauge

Labels:

  • component: node
  • directory: One of genlayer.db, keystore, logs
  • node: Node address (hex format)

Node Status Metrics

genlayer_node_blocks_behind

Number of blocks behind the latest block.

Type: Gauge

Labels:

  • node: Node address (hex format)

genlayer_node_latest_block

Latest block number in the network.

Type: Gauge

Labels:

  • node: Node address (hex format)

genlayer_node_processing_block

Currently processing block number.

Type: Gauge

Labels:

  • node: Node address (hex format)

genlayer_node_synced_block

Last synced block number.

Type: Gauge

Labels:

  • node: Node address (hex format)

genlayer_node_synced

Node synchronization status (1 = synced, 0 = not synced).

Type: Gauge

Labels:

  • node: Node address (hex format)

genlayer_node_uptime_seconds

Node uptime in seconds.

Type: Gauge

Labels:

  • component: node
  • node: Node address (hex format)

Transaction Metrics

genlayer_node_transactions_accepted_synced_total

Total number of accepted and synced transactions.

Type: Gauge

Labels:

  • node: Node address (hex format)

genlayer_node_transactions_activated_total

Total number of activated transactions.

Type: Gauge

Labels:

  • node: Node address (hex format)

genlayer_node_transactions_leader_proposed_total

Total number of transactions proposed as leader.

Type: Gauge

Labels:

  • node: Node address (hex format)

genlayer_node_transactions_leader_revealed_total

Total number of transactions revealed as leader.

Type: Gauge

Labels:

  • node: Node address (hex format)

genlayer_node_transactions_validator_commit_total

Total number of validator commit votes.

Type: Gauge

Labels:

  • node: Node address (hex format)

genlayer_node_transactions_validator_reveal_total

Total number of validator reveal votes.

Type: Gauge

Labels:

  • node: Node address (hex format)

Go Runtime Metrics

The endpoint also exposes standard Go runtime metrics including:

  • go_gc_duration_seconds - Garbage collection duration summary
  • go_goroutines - Number of active goroutines
  • go_memstats_* - Go memory statistics (heap, stack, GC)
  • go_threads - Number of OS threads

Process Metrics

Standard process metrics are also available:

  • process_cpu_seconds_total - Total CPU time
  • process_resident_memory_bytes - Resident memory size
  • process_virtual_memory_bytes - Virtual memory size
  • process_open_fds - Number of open file descriptors
  • process_network_receive_bytes_total - Network bytes received
  • process_network_transmit_bytes_total - Network bytes transmitted

Prometheus Handler Metrics

Metrics about the metrics endpoint itself:

  • promhttp_metric_handler_requests_total - Total scrape requests by status code
  • promhttp_metric_handler_requests_in_flight - Current scrapes being served

Configuration

Metrics collection can be configured in the node configuration file:

metrics:
  interval: "15s"        # Default interval for all collectors
  collectors:
    node:
      enabled: true      # Enable/disable node metrics
      interval: "30s"    # Optional: Override default interval
    genvm:
      enabled: true      # Enable/disable GenVM metrics
      # Uses default interval (15s)
    webdriver:
      enabled: true      # Enable/disable WebDriver metrics
      interval: "60s"    # Optional: Override default interval

Default Values

  • metrics.interval: 15s (applies to all collectors by default)
  • enabled: true (for each collector)
  • interval: Uses metrics.interval if not specified per collector

Configuration Priority

  1. Collector-specific interval (if specified)
  2. Global metrics.interval (if specified)
  3. System default (15s)

Troubleshooting

No Metrics for GenVM

GenVM processes are ephemeral and only run when executing smart contracts. If you don't see GenVM metrics, it's likely that no contracts are currently being executed.

WebDriver Metrics Missing

Ensure the WebDriver container is running:

docker ps | grep genlayer-node-webdriver

If not running, start it:

task docker:webdriver:docker-compose:up:detach

Metrics Not Updating

Check if metrics collection is enabled in your configuration and that the node has been restarted after configuration changes.

Performance Considerations

  • Collection intervals can be increased to reduce overhead further
  • Each collector runs independently and won't block others if one fails
GenLayer Testgen_call