> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genlabs.co/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON-RPC API

> Full JSON-RPC reference for the Grid - every method, parameter, and response shape.

Grid exposes a JSON-RPC 2.0 endpoint over HTTPS. The CLI, the Rust SDK, and any
third-party integration call the same surface.

## How to call it

A JSON-RPC call is a `POST` of a JSON body to a single URL. The endpoint
depends on the network you target. For DevNet:

<Note>
  **DevNet access.** DevNet requires a bearer token. Ask your Gen Labs contact for one and substitute it for `<your-jwt>` in the examples below.
</Note>

```bash theme={null}
curl -s -X POST https://devnet.genlabs.co/rpc/ \
  -H 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"gen_getVersion","params":{}}'
```

Find the endpoint for your network in [Network status](/user-guide/network-status).

## Envelope

Every request follows JSON-RPC 2.0:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "gen_<methodName>",
  "params": { /* method-specific */ }
}
```

Successful responses:

```json theme={null}
{ "jsonrpc": "2.0", "id": 1, "result": { /* method-specific */ } }
```

Errors:

```json theme={null}
{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "Invalid params" } }
```

Method names are camelCase with a `gen_` prefix (`gen_getActivation`, not
`gen_GetActivation`).

## Error model

Errors fall into three layers, checked in this order:

1. **Transport errors** - the request never reached the validator. HTTP status codes apply (`502`, `504`). Retry with backoff.
2. **JSON-RPC errors** - the request was malformed. Standard codes: `-32600` invalid request, `-32601` method not found, `-32602` invalid params, `-32603` internal error. Do not retry without fixing the request.
3. **Application errors** - the request was valid but the operation failed (insufficient balance, unknown account, etc.). Returned as a `result` payload with a status field, not as an `error`. Treat as a state to handle, not a retry signal.

## Binary payloads

Methods that take or return raw bytes (`gen_submitActivation`, `gen_view`,
`gen_simulateActivation`, `gen_getStorageAt`) represent those bytes as
base64-encoded strings in JSON-RPC. The Rust SDK handles the encoding for you.

## Versioning

Two version fields matter, both returned by `gen_getVersion`:

* `release_version` - the validator's release.
* `rpc_protocol_version` - the wire-protocol version. Pin against this in production; minor revisions can add fields, breaking changes increment the version.

Clients may pass an `X-Gen-Protocol-Version` header (e.g. `0.1.0`) on any
request. When present, the server validates it and rejects mismatches with
error code `-32001`. When absent, no validation occurs.

## Methods

Sixteen public methods, grouped by domain. Click any method to expand its parameters, response shape, and an example request.

### Activations

<AccordionGroup>
  <Accordion title="gen_submitActivation">
    Sends a signed activation to the network.

    **Parameters**

    <ParamField path="payload" type="Base64Bytes" required>
      Arbitrary binary data encoded as a base64 string.
    </ParamField>

    **Result**

    <ResponseField name="result" type="ActivationId" required>
      Activation ID assigned to the submitted activation
    </ResponseField>

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_submitActivation", "params": {"request": "<...>"}}'
    ```
  </Accordion>

  <Accordion title="gen_simulateActivation">
    Simulates an activation without submitting it to the network.  The activation is executed locally and all continuations are followed BFS-style. State queries are resolved against the specified block height (if provided).

    **Parameters**

    <ParamField path="block_index" type="U64String | null" />

    <ParamField path="payload" type="Base64Bytes" required>
      Arbitrary binary data encoded as a base64 string.
    </ParamField>

    **Result**

    <ResponseField name="activation_results" type="SimulationActivationResult[]" required>
      Per-activation results in BFS execution order.

      <Expandable title="item properties">
        <ResponseField name="activation" type="Base64Bytes" required>
          Borsh-serialized activation envelope.
        </ResponseField>

        <ResponseField name="activation_id" type="ActivationId" required>
          ID of the activation that was executed.
        </ResponseField>

        <ResponseField name="entity_id" type="EntityId" required>
          Entity targeted by this activation.
        </ResponseField>

        <ResponseField name="operation_results" type="OperationResult[]" required>
          Per-operation results (changes, events, continuations).

          <Expandable title="item properties">
            <ResponseField name="changes" type="StorageChange[]" required>
              Storage changes made by this operation.

              <Expandable title="item properties">
                <ResponseField name="key" type="H256" required>
                  Global storage key (32 bytes), serialized as a `0x`-prefixed hex string.
                </ResponseField>

                <ResponseField name="value" type="Base64Bytes" required>
                  Storage value as base64 bytes.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="continuations" type="ActivationId[]" required>
              Continuations (internal activation IDs) created by this operation.
            </ResponseField>

            <ResponseField name="events" type="Event[]" required>
              Events emitted by this operation.

              <Expandable title="item properties">
                <ResponseField name="event_name" type="string" required>
                  Human-readable name describing the payload.
                </ResponseField>

                <ResponseField name="event_type" type="string" required>
                  Logical subsystem that emitted the event (e.g., `"Gvm"`).
                </ResponseField>

                <ResponseField name="operation_index" type="integer (uint32)" required>
                  Operation index that produced this event.
                </ResponseField>

                <ResponseField name="payload" type="Base64Bytes" required>
                  Raw payload bytes of the event payload (base64 on the wire).
                </ResponseField>

                <ResponseField name="timestamp" type="string" required>
                  RFC3339 timestamp describing when the event was emitted.
                </ResponseField>

                <ResponseField name="version" type="integer (uint16)" required>
                  Event schema version.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="target_component" type="ComponentId" required>
              The component that was the target of this operation.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="outcome" type="ExecutionOutcome" required>
          Execution outcome (success or failure with message).
        </ResponseField>
      </Expandable>
    </ResponseField>

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_simulateActivation", "params": {"request": "<...>"}}'
    ```
  </Accordion>

  <Accordion title="gen_getActivation">
    Returns activation details by id. Returns JSON-RPC NOT\_FOUND if the activation does not exist.

    **Parameters**

    <ParamField path="activation_id" type="ActivationId" required />

    **Result**

    <ResponseField name="activation" type="ActivationInfo" required>
      Activation details returned by the API.

      <Expandable title="properties">
        <ResponseField name="activation" type="object" required>
          Activation body/details (schema depends on activation type).
        </ResponseField>

        <ResponseField name="activation_type" type="string" required>
          Activation type discriminator (e.g., `"GVM"`).
        </ResponseField>

        <ResponseField name="continuations" type="ActivationId[]" required>
          Continuation activation IDs, if any.
        </ResponseField>

        <ResponseField name="end_block" type="U64String" required>
          Block index where the activation ended.
        </ResponseField>

        <ResponseField name="events" type="Event[]" required>
          Domain-specific events emitted during execution.

          <Expandable title="item properties">
            <ResponseField name="event_name" type="string" required>
              Human-readable name describing the payload.
            </ResponseField>

            <ResponseField name="event_type" type="string" required>
              Logical subsystem that emitted the event (e.g., `"Gvm"`).
            </ResponseField>

            <ResponseField name="operation_index" type="integer (uint32)" required>
              Operation index that produced this event.
            </ResponseField>

            <ResponseField name="payload" type="Base64Bytes" required>
              Raw payload bytes of the event payload (base64 on the wire).
            </ResponseField>

            <ResponseField name="timestamp" type="string" required>
              RFC3339 timestamp describing when the event was emitted.
            </ResponseField>

            <ResponseField name="version" type="integer (uint16)" required>
              Event schema version.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="from" type="EntityId" required>
          Sender entity.
        </ResponseField>

        <ResponseField name="gas_used" type="ConsumedGas" required>
          Gas consumed by this activation, broken down by resource type.

          <Expandable title="properties">
            <ResponseField name="cpu" type="U128String" required>
              A u128 value serialized as a decimal string to preserve precision.
            </ResponseField>

            <ResponseField name="network" type="U128String" required>
              A u128 value serialized as a decimal string to preserve precision.
            </ResponseField>

            <ResponseField name="storage_io" type="U128String" required>
              A u128 value serialized as a decimal string to preserve precision.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="parent_activation" type="ActivationId | null">
          Parent activation ID, if any.
        </ResponseField>

        <ResponseField name="start_block" type="U64String" required>
          Block index where the activation started.
        </ResponseField>

        <ResponseField name="status" type="ActivationStatus" required>
          Typed execution status.
        </ResponseField>

        <ResponseField name="to" type="EntityId" required>
          Target entity.
        </ResponseField>
      </Expandable>
    </ResponseField>

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getActivation", "params": {"request": "<...>"}}'
    ```
  </Accordion>

  <Accordion title="gen_getTrace">
    Returns trace details by id.

    **Parameters**

    <ParamField path="trace_id" type="TransactionId" required />

    **Result**

    <ResponseField name="activations" type="ActivationId[]" required />

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getTrace", "params": {"request": "<...>"}}'
    ```
  </Accordion>

  <Accordion title="gen_view">
    Executes a read-only activation payload. No state changes occur.

    **Parameters**

    <ParamField path="payload" type="Base64Bytes" required>
      Arbitrary binary data encoded as a base64 string.
    </ParamField>

    **Result**

    <ResponseField name="bytes" type="Base64Bytes" required>
      Opaque result bytes encoded as base64 on the wire.
    </ResponseField>

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_view", "params": {"request": "<...>"}}'
    ```
  </Accordion>
</AccordionGroup>

### Accounts and balances

<AccordionGroup>
  <Accordion title="gen_getAccount">
    Returns account details by address.

    **Parameters**

    <ParamField path="account" type="GvmAccount" required>
      Bech32m-encoded GvmAccount: HRP grd@ over 36 bytes (entity\_id || 0u32\_LE).
    </ParamField>

    **Result**

    <ResponseField name="components" type="GvmComponentId[]" required>
      Components installed on the account.

      <Expandable title="item properties">
        <ResponseField name="component_entity_id" type="EntityId" required>
          Unique 256-bit identifier for an entity in the Grid VM.

          Encoded as a 0x-prefixed, 64-character hex string on the JSON-RPC wire.
        </ResponseField>

        <ResponseField name="header" type="GvmComponentHeader" required>
          Shared header for GVM component metadata.

          This header is used both on the host and in the VM as the canonical representation of GVM component identity.

          <Expandable title="properties">
            <ResponseField name="component_code_id" type="GvmComponentCodeId" required>
              Uniquely represents a single code artifact.

              A code artifact is identified by the push that uploaded it and the role index within that push. This is used to identify executable code in the GVM.

              <Expandable title="properties">
                <ResponseField name="component_type_index" type="ComponentTypeIndex" required>
                  Index of a role within a GVM system.
                </ResponseField>

                <ResponseField name="contract_code_id" type="GvmContractCodeId" required />
              </Expandable>
            </ResponseField>

            <ResponseField name="contract" type="GvmContract" required />

            <ResponseField name="index" type="GvmComponentIndex" required>
              Index of a component within a GVM system.

              `0` is reserved for the account component, while values greater than `0` represent explicit user component indices.
            </ResponseField>

            <ResponseField name="version" type="ContractVersion" required>
              Version of a GVM system implementation.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="owner" type="ComponentOwner" required>
      Owner of the account.
    </ResponseField>

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getAccount", "params": {"request": "<...>"}}'
    ```
  </Accordion>

  <Accordion title="gen_getBalance">
    Returns the routed fungible balance for an account.

    **Parameters**

    <ParamField path="account" type="GvmAccount" required>
      Bech32m-encoded GvmAccount: HRP grd@ over 36 bytes (entity\_id || 0u32\_LE).
    </ParamField>

    <ParamField path="gvm_contract" type="GvmContract | null" />

    **Result**

    <ResponseField name="result" type="Amount" required>
      Balance amount for the requested contract, or the configured GEN contract when omitted
    </ResponseField>

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getBalance", "params": {"request": "<...>"}}'
    ```
  </Accordion>

  <Accordion title="gen_getBalances">
    Returns all configured fungible balances for an account.

    **Parameters**

    <ParamField path="account" type="GvmAccount" required>
      Bech32m-encoded GvmAccount: HRP grd@ over 36 bytes (entity\_id || 0u32\_LE).
    </ParamField>

    **Result**

    <ResponseField name="balances" type="object" required />

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getBalances", "params": {"request": "<...>"}}'
    ```
  </Accordion>
</AccordionGroup>

### Blocks

<AccordionGroup>
  <Accordion title="gen_getBlock">
    Returns an aggregated closed block for a given block index.

    **Parameters**

    <ParamField path="block_index" type="U64String" required>
      A u64 value serialized as a decimal string to preserve precision.
    </ParamField>

    **Result**

    <ResponseField name="block_index" type="U64String" required>
      A u64 value serialized as a decimal string to preserve precision.
    </ResponseField>

    <ResponseField name="order_events" type="BlockOrderEvent[]" required>
      <Expandable title="item properties">
        <ResponseField name="activation_id" type="ActivationId" required>
          Activation ID for which this event is recorded.
        </ResponseField>

        <ResponseField name="entity" type="EntityId" required>
          Entity ID on which this activation was executed.
        </ResponseField>

        <ResponseField name="kind" type="BlockOrderEventKind" required>
          Event payload (start or end).
        </ResponseField>

        <ResponseField name="timestamp" type="U64String" required>
          Lamport timestamp associated with this event.
        </ResponseField>
      </Expandable>
    </ResponseField>

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getBlock", "params": {"request": "<...>"}}'
    ```
  </Accordion>

  <Accordion title="gen_getCurrentBlockIndex">
    Returns the latest finalized block index known to this RPC unit.

    **Parameters**

    <ParamField path="request" type="GetCurrentBlockIndexRequest" required>
      Request for the GetCurrentBlockIndex RPC.
    </ParamField>

    **Result**

    <ResponseField name="block_index" type="U64String" required>
      A u64 value serialized as a decimal string to preserve precision.
    </ResponseField>

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getCurrentBlockIndex", "params": {"request": "<...>"}}'
    ```
  </Accordion>
</AccordionGroup>

### Contracts and components

<AccordionGroup>
  <Accordion title="gen_getContract">
    Returns contract metadata and ABI.

    **Parameters**

    <ParamField path="contract" type="GvmContract" required />

    **Result**

    <ResponseField name="abis" type="Abi[]" required>
      ABIs for all components in the contract.
    </ResponseField>

    <ResponseField name="details" type="ContractDetails" required>
      Contract details (code ID, owner).

      <Expandable title="properties">
        <ResponseField name="contract_code_id" type="GvmContractCodeId" required>
          The contract code identifier.
        </ResponseField>

        <ResponseField name="owner" type="ComponentOwner" required>
          The owner of the contract.
        </ResponseField>
      </Expandable>
    </ResponseField>

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getContract", "params": {"request": "<...>"}}'
    ```
  </Accordion>

  <Accordion title="gen_getComponent">
    Returns component metadata and ABI.

    **Parameters**

    <ParamField path="component_id" type="GvmComponentId" required>
      Identifies a specific applicative GVM component instance (component entity + header). Contains the storage key plus applicative information for validations and orientation in the GVM.

      Serde/JSON uses the structured `component_entity_id` + `header` representation of this type.

      For human-readable CLI input/output, \[`fmt::Display`] and \[`FromStr`] use two or four comma-separated bech32m parts (HRP `grd@`), not a single bech32m string.

      # Equality and Hashing Semantics

      `GvmComponentId` uses custom equality, hashing, and ordering: if either component has `ContractVersion::LATEST`, the version comparison is skipped. This allows latest-version matching to act as a wildcard that matches any version, which is useful for checks where the exact version shouldn't matter.

      **Important**: The version field is NOT included in hashing or equality comparisons when `Latest` is involved, ensuring consistent behavior with HashMap/HashSet lookups.

      <Expandable title="properties">
        <ParamField path="component_entity_id" type="EntityId" required>
          Unique 256-bit identifier for an entity in the Grid VM.

          Encoded as a 0x-prefixed, 64-character hex string on the JSON-RPC wire.
        </ParamField>

        <ParamField path="header" type="GvmComponentHeader" required>
          Shared header for GVM component metadata.

          This header is used both on the host and in the VM as the canonical representation of GVM component identity.

          <Expandable title="properties">
            <ParamField path="component_code_id" type="GvmComponentCodeId" required>
              Uniquely represents a single code artifact.

              A code artifact is identified by the push that uploaded it and the role index within that push. This is used to identify executable code in the GVM.

              <Expandable title="properties">
                <ParamField path="component_type_index" type="ComponentTypeIndex" required>
                  Index of a role within a GVM system.
                </ParamField>

                <ParamField path="contract_code_id" type="GvmContractCodeId" required />
              </Expandable>
            </ParamField>

            <ParamField path="contract" type="GvmContract" required />

            <ParamField path="index" type="GvmComponentIndex" required>
              Index of a component within a GVM system.

              `0` is reserved for the account component, while values greater than `0` represent explicit user component indices.
            </ParamField>

            <ParamField path="version" type="ContractVersion" required>
              Version of a GVM system implementation.
            </ParamField>
          </Expandable>
        </ParamField>
      </Expandable>
    </ParamField>

    **Result**

    <ResponseField name="abi" type="Abi" required>
      ABI for the component.
    </ResponseField>

    <ResponseField name="component_id" type="GvmComponentId" required>
      Resolved component identifier (includes index when resolved via default route).

      <Expandable title="properties">
        <ResponseField name="component_entity_id" type="EntityId" required>
          Unique 256-bit identifier for an entity in the Grid VM.

          Encoded as a 0x-prefixed, 64-character hex string on the JSON-RPC wire.
        </ResponseField>

        <ResponseField name="header" type="GvmComponentHeader" required>
          Shared header for GVM component metadata.

          This header is used both on the host and in the VM as the canonical representation of GVM component identity.

          <Expandable title="properties">
            <ResponseField name="component_code_id" type="GvmComponentCodeId" required>
              Uniquely represents a single code artifact.

              A code artifact is identified by the push that uploaded it and the role index within that push. This is used to identify executable code in the GVM.

              <Expandable title="properties">
                <ResponseField name="component_type_index" type="ComponentTypeIndex" required>
                  Index of a role within a GVM system.
                </ResponseField>

                <ResponseField name="contract_code_id" type="GvmContractCodeId" required />
              </Expandable>
            </ResponseField>

            <ResponseField name="contract" type="GvmContract" required />

            <ResponseField name="index" type="GvmComponentIndex" required>
              Index of a component within a GVM system.

              `0` is reserved for the account component, while values greater than `0` represent explicit user component indices.
            </ResponseField>

            <ResponseField name="version" type="ContractVersion" required>
              Version of a GVM system implementation.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="owner" type="ComponentOwner" required>
      Owner of the component.
    </ResponseField>

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getComponent", "params": {"request": "<...>"}}'
    ```
  </Accordion>

  <Accordion title="gen_getAbiByContractId">
    Returns contract ABIs by contract ID.

    **Parameters**

    <ParamField path="contract" type="GvmContract" required />

    **Result**

    <ResponseField name="abis" type="Abi[]" required>
      ABIs for all components in the contract.
    </ResponseField>

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getAbiByContractId", "params": {"request": "<...>"}}'
    ```
  </Accordion>

  <Accordion title="gen_getAbiByContractCodeId">
    Returns contract ABIs by contract code ID.

    **Parameters**

    <ParamField path="contract_code_id" type="GvmContractCodeId" required />

    **Result**

    <ResponseField name="abis" type="Abi[]" required>
      ABIs for all components in the contract code.
    </ResponseField>

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getAbiByContractCodeId", "params": {"request": "<...>"}}'
    ```
  </Accordion>

  <Accordion title="gen_getStorageAt">
    Returns the raw storage value for a component at a given key.

    **Parameters**

    <ParamField path="component_id" type="ComponentId" required />

    <ParamField path="key" type="H256" required>
      256-bit hash value. Encoded as a 0x-prefixed, 64-character hex string.
    </ParamField>

    **Result**

    <ResponseField name="result" type="Base64Bytes | null" required>
      Base64Bytes or `null` if the key is missing
    </ResponseField>

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getStorageAt", "params": {"request": "<...>"}}'
    ```
  </Accordion>
</AccordionGroup>

### Node

<AccordionGroup>
  <Accordion title="gen_getVersion">
    Returns the artifact release version and developer-owned RPC protocol version.

    **Parameters**

    <ParamField path="request" type="GetVersionRequest" required>
      Request for the GetVersion RPC.
    </ParamField>

    **Result**

    <ResponseField name="release_version" type="string" required />

    <ResponseField name="rpc_protocol_version" type="string" required />

    **Example request**

    ```bash theme={null}
    curl -s -X POST $RPC_URL \
      -H 'Content-Type: application/json' \
      --data '{"jsonrpc": "2.0", "id": 1, "method": "gen_getVersion", "params": {"request": "<...>"}}'
    ```
  </Accordion>
</AccordionGroup>