Block API: Query Sundial L2 Blocks and State Queue

Two endpoints expose block-level data on the Sundial L2. Use GET /block to retrieve the transactions included in a specific block by its header hash, and GET /stateQueue to inspect the linked list of committed block headers that lives on L1. Together they give you visibility into both individual block contents and the overall progression of the L2 chain.

GET /block and GET /stateQueue are available on full (monolith) nodes only. The related GET /stateQueue/root-unit-diagnostics is also served by api-role nodes and is useful for health monitoring without performing a full state-queue fetch.

GET /block — Query Block Transactions

Retrieve the list of transaction hashes included in a Sundial L2 block, identified by its 56-character header hash. The node looks up the block and returns the hashes of every transaction committed to that block.

Query Parameters

string

required

The 56-character hex block header hash. Must be a valid hex string of exactly 56 characters — not 64 (which is a transaction hash length). Block header hashes on Sundial are 28 bytes, represented as 56 hex characters.

Example

curl "https://rpc.testnet.sundialprotocol.com/block?header_hash=a3f9e2b1c4d7..."

Responses

Success (200)
Invalid Hash (400)
Not Found

{
  "hashes": [
    "9e4f3a2b1c0d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f",
    "1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b"
  ]
}

Each entry in hashes is a 64-character hex transaction hash. An empty hashes array indicates a block with no transactions. Use each hash with GET /tx to retrieve the full CBOR of individual transactions.

{ "error": "Invalid block hash: <header_hash>" }

Returned when header_hash is missing, not a valid hex string, or not exactly 56 characters long.

An unrecognized header hash returns an empty hashes array rather than a 404. If you receive an empty array for a hash you expect to exist, verify the hash length (56 hex characters) and confirm the block has been committed.

Fetching Full Transactions for a Block

Combine GET /block with GET /tx to retrieve complete transaction data for every transaction in a block:

async function getBlockTransactions(
  headerHash: string
): Promise<string[]> {
  const blockRes = await fetch(
    `https://rpc.testnet.sundialprotocol.com/block` +
      `?header_hash=${encodeURIComponent(headerHash)}`
  );
  const { hashes } = await blockRes.json();

  const txCbors = await Promise.all(
    hashes.map(async (txHash: string) => {
      const txRes = await fetch(
        `https://rpc.testnet.sundialprotocol.com/tx?tx_hash=${txHash}`
      );
      const { tx } = await txRes.json();
      return tx; // hex-cbor
    })
  );

  return txCbors;
}

GET /stateQueue — Query the L1 State Queue

Fetch the current state-queue linked list from L1. The state queue is an on-chain data structure that tracks every block header committed by L2 operators. Each entry in the queue corresponds to one committed L2 block and records the header hash that anchors it to the Sundial chain. The endpoint fetches state-queue UTxOs from the settlement L1 via the Sundial SDK, logs a visual representation server-side, and returns the non-empty header keys.

Example

curl "https://rpc.testnet.sundialprotocol.com/stateQueue"

Response

{
  "headers": [
    "a3f9e2b1c4d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3",
    "b4a0f3c2d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2"
  ]
}

Each entry in headers is a 56-character hex block header hash representing a committed block on the state queue.

Cross-reference the header hashes from GET /stateQueue with GET /block to map each committed block to its constituent transactions.

GET /stateQueue/root-unit-diagnostics — State Queue Health

Check the health of the state-queue root unit — the single on-chain token that anchors the entire state-queue linked list. This endpoint is available on both full nodes and api-role nodes, making it suitable for automated monitoring and alerting.

Example

curl "https://rpc.testnet.sundialprotocol.com/stateQueue/root-unit-diagnostics"

Responses

Healthy (200)
Invalid (200)
Provider Error (503)

{
  "status": "ok",
  "resetInProgress": false,
  "stateQueueAddress": "addr1...",
  "rootUnit": "<policy-id+asset-name>",
  "count": 1,
  "outRefs": ["<txHash>#<outputIndex>"]
}

A status of "ok" with count: 1 means the state queue has exactly one root unit, which is the healthy state.

{
  "status": "invalid",
  "resetInProgress": false,
  "stateQueueAddress": "addr1...",
  "rootUnit": "<policy-id+asset-name>",
  "count": 0,
  "outRefs": []
}

A status of "invalid" with count not equal to 1 (zero or more than one root unit) indicates the state queue needs attention. Contact the Sundial team or consult the operator repair runbook.

{
  "status": "error",
  "cause": "L1 provider request timed out"
}

Returned when the L1 provider query fails. This indicates a transient connectivity issue between the node and its L1 backend — retry after a short delay.

Operator Endpoints

The following endpoints are intended for node operators and are only available on full (monolith) nodes unless noted.

GET /stateQueue/repair-root-units

Burn duplicate state-queue root units when the root-unit count is greater than 1. This is a targeted repair operation — faster than a full node reset when only the root unit count is wrong. After a successful repair, the root unit count is brought to 0; run GET /init once afterward to mint a fresh single root unit.

curl "https://rpc.testnet.sundialprotocol.com/stateQueue/repair-root-units"

{ "message": "State-queue root-unit repair completed successfully!" }

This endpoint is lock-guarded — a concurrent reset or init operation returns 409 {"error":"Reset already in progress"}.

GET /commitment-wallet/balance

Return the lovelace balance of the block-commitment operator wallet. This endpoint is available on both full nodes and api-role nodes and is useful for alerting when the commitment wallet is running low.

curl "https://rpc.testnet.sundialprotocol.com/commitment-wallet/balance"

{ "lovelaceBalance": "5000000000" }

The balance is returned as a string to preserve full integer precision.

Block Lifecycle

Understanding where a block sits in its lifecycle helps you interpret state-queue and block query results:

Pending — committed to L1, awaiting maturity

An operator has submitted the block header to the L1 state queue, but the block has not yet reached its maturity window. During this period, Watchers (Provers) can submit fraud proofs if the block is invalid. The header hash is present in GET /stateQueue output.

Mature — eligible for merging into confirmed state

The maturity window has elapsed without a successful fraud proof. The block’s transactions are finalized and its outputs are spendable. The operator can now trigger a merge to consolidate the block into confirmed state.

Merged — incorporated into confirmed ledger state

The block has been merged into the Sundial confirmed state. Its transactions are permanently recorded and reachable via GET /block.

The Sundial L2 uses an optimistic rollup model — blocks are considered valid by default and only rolled back if a fraud proof is successfully submitted during the maturity window. This means a transaction visible in a pending block is not yet finalized. Wait for the block to reach mature or merged status before treating outputs as settled.

Node API

SDKs & Libraries

Operator Toolkit

Block API: Query Sundial L2 Blocks and State Queue

GET /block — Query Block Transactions

Query Parameters

Example

Responses

Fetching Full Transactions for a Block

GET /stateQueue — Query the L1 State Queue

Example

Response

GET /stateQueue/root-unit-diagnostics — State Queue Health

Example

Responses

Operator Endpoints

GET /stateQueue/repair-root-units

GET /commitment-wallet/balance

Block Lifecycle

​GET /block — Query Block Transactions

​Query Parameters

​Example

​Responses

​Fetching Full Transactions for a Block

​GET /stateQueue — Query the L1 State Queue

​Example

​Response

​GET /stateQueue/root-unit-diagnostics — State Queue Health

​Example

​Responses

​Operator Endpoints

​GET /stateQueue/repair-root-units

​GET /commitment-wallet/balance

​Block Lifecycle

GET /block — Query Block Transactions

Query Parameters

Example

Responses

Fetching Full Transactions for a Block

GET /stateQueue — Query the L1 State Queue

Example

Response

GET /stateQueue/root-unit-diagnostics — State Queue Health

Example

Responses

Operator Endpoints

GET /stateQueue/repair-root-units

GET /commitment-wallet/balance

Block Lifecycle