BoLD validator API

When BoLD is activated, validators have access to an optional API that Nitro provides, which provides information about the assertions being posted and the current challenges going on.

This page describes the rationale behind providing this API and the available endpoints.

Why do we need an API?

BoLD is a complex protocol that enables validators to defend claims about an Arbitrum chain on its parent chain. By default, uncontested claims are confirmed within 7 days, and contested claims can be confirmed within 14 days. Within that sliding window, there can be a significant amount of challenges and activities of validators making moves to defend their claims. Nitro is equipped to make moves on behalf of honest validators automatically and logs a lot of information about ongoing challenges.

However, the amount of information logged between a simple Alice vs. Bob dispute is enormous. Each move made in a challenge emits a log, and there are many other things occurring in a validator node's runtime that are also logged in the process. Because BoLD challenges can be concurrent, we can quickly see an explosion of logs if many participants are involved.

t=2023-11-03T21:03:08+0000 lvl=info msg="Successfully bisected edge" service=edge-tracker      name= challengeType=block_challenge_edge bisectedFrom=16 bisectedFromMerkle=0x87d91006 bisectedTo=8  bisectedToMerkle=0xb3321c66
t=2023-11-03T21:03:08+0000 lvl=info msg="Tracking edge" service=edge-tracker      id=0xc66e7e5d fromBatch=0 toBatch=1 startHeight=0  endHeight=8  endCommit=0xb3321c66 startCommit=0x0107305d validatorName=        challengeType=block_challenge_edge
t=2023-11-03T21:03:08+0000 lvl=info msg="Tracking edge"                          service=edge-tracker      startHeight=8  startCommit=0xb3321c66 endHeight=16 endCommit=0x87d91006 id=0xbb16c213 fromBatch=0 toBatch=1 validatorName=        challengeType=block_challenge_edge

Aside from logs, we do not have a good way of understanding if a challenge is going in favor of the honest party. Since we cannot rely solely on logs to understand the progression of a BoLD challenge, Nitro includes an API that provides information to understand ongoing challenges and the health of the honest validators involved.

Enabling and configuring the API

To enable the API, include the following parameters in the configuration of your validator:

Parameter	Description
--node.bold.api	Set to true to enable the API
--node.bold.api-host	IP to listen on (defaults to 127.0.0.1)
--node.bold.api-port	Port to listen on (defaults to 9393)

Endpoints available

The following endpoints are available at the configured host and port to query information from the API. Send a GET request to access them:

/api/v1/assertions

Lists all assertions up to chain head.

This request will return an array of objects with information about each assertion.

/api/v1/assertions/<assertion-hash>

Returns information of a specific assertion.

/api/v1/challenge/<assertion-hash>/edges

Returns all edges for a challenged assertion.

This request will return an array of objects with information about each edge.

/api/v1/challenge/<assertion-hash>/edges/history/<history-commitment>

Returns information about a specific edge, given its history commitment.

/api/v1/challenge/<assertion-hash>/ministakes

Returns all the ministakes bonded under a challenged assertion.

/api/v1/tracked/royal-edges

Returns the locally-tracked, royal edges kept in-memory by the validator.

/api/v1/healthz

Checks if the API server is ready to serve queries. Returns a status of 200 if it is ready. Notice that this request will not return any result.