Skip to content

State Chain API

Endpoints for interacting with the state chain -- the DAO governance layer that manages network parameters, timekeeper keys, and other shared state.

Get Latest Block (Tip)

GET /statechain/tip

Returns the most recent state chain block.

Response

{
  "index": 42,
  "prev_hash": "a1b2c3d4...",
  "ops": [
    {
      "type": "set",
      "key": "emission/rate",
      "value": "1000"
    }
  ],
  "signatures": [
    {
      "public_key": "f1a2b3c4...",
      "signature": "e6f7a8b9..."
    }
  ],
  "timestamp": 1709500000000000000,
  "hash": "b5c6d7e8..."
}

See State Chain Block for field descriptions.

Example

curl http://localhost:8080/statechain/tip

Get Block by Index

GET /statechain/blocks/{index}

Returns a single state chain block by its position in the chain.

Path Parameters

Parameter Type Description
index integer Zero-based block index

Response

Returns a State Chain Block.

Errors

Status Description
404 Block not found

Example

curl http://localhost:8080/statechain/blocks/42

Get Block Range

GET /statechain/blocks

Returns a range of state chain blocks.

Query Parameters

Parameter Type Default Description
start integer 0 Starting index (inclusive)
limit integer 20 Maximum number of blocks to return

Response

Returns an array of State Chain Block objects, ordered by index.

Example

curl "http://localhost:8080/statechain/blocks?start=10&limit=5"

Get State Value by Key

GET /statechain/kv/{key}

Returns the current value for a key in the state chain's key-value store. Keys can contain slashes (e.g., emission/rate, timekeeper/keys/0).

Path Parameters

Parameter Type Description
key string State key (may contain / separators)

Response

{
  "key": "emission/rate",
  "value": "1000"
}
Field Type Description
key string The requested key
value string Current value (string-encoded)

Errors

Status Description
404 Key not found

Example

curl http://localhost:8080/statechain/kv/emission/rate

Get All State KV Entries

GET /statechain/kv

Returns all key-value entries in the state chain store.

Response

[
  {
    "key": "emission/rate",
    "value": "1000"
  },
  {
    "key": "timekeeper/keys/0",
    "value": "f1a2b3c4..."
  }
]

Example

curl http://localhost:8080/statechain/kv

Get DAO Keyset

GET /statechain/keyset

Returns the current DAO keyset -- the set of authorised signing keys and the threshold required to approve state chain blocks.

Response

{
  "keys": [
    "f1a2b3c4...",
    "a5b6c7d8...",
    "c9d0e1f2..."
  ],
  "threshold": 2
}
Field Type Description
keys array Hex-encoded ed25519 public keys of authorised signers
threshold integer Minimum number of signatures required to approve a block

Threshold signatures

A state chain block must carry at least threshold valid signatures from keys in the keyset. For example, with 3 keys and threshold 2, any 2 of the 3 authorised signers can approve a governance action. See Governance.

Example

curl http://localhost:8080/statechain/keyset

Submit State Chain Block

POST /statechain/blocks

Submits a new state chain block. The block must carry sufficient signatures from the current keyset.

Request Body

{
  "index": 43,
  "prev_hash": "b5c6d7e8...",
  "ops": [
    {
      "type": "set",
      "key": "emission/rate",
      "value": "2000"
    }
  ],
  "signatures": [
    {
      "public_key": "f1a2b3c4...",
      "signature": "e6f7a8b9..."
    },
    {
      "public_key": "a5b6c7d8...",
      "signature": "d1e2f3a4..."
    }
  ],
  "timestamp": 1709500060000000000
}

State Chain Block Object

Field Type Description
index integer Block position (must equal previous index + 1)
prev_hash string Hash of the previous state chain block
ops array Array of operations to apply
signatures array Signatures from authorised keyset members
timestamp integer Unix nanosecond timestamp
hash string SHA-256 hash of block contents (computed by node)

Operation Types

Type Fields Description
set key, value Set a key-value pair in the state store
delete key Remove a key from the state store

Signature Object

Field Type Description
public_key string Hex-encoded ed25519 public key (must be in the keyset)
signature string ed25519 signature over the block hash

Response

{
  "hash": "c7d8e9f0...",
  "index": 43
}

Errors

Status Description
400 Invalid block (wrong index, bad prev_hash, insufficient signatures, invalid operation)

Index must be sequential

The submitted block's index must equal the current tip's index + 1, and prev_hash must match the current tip's hash. Gaps and forks are rejected.