Skip to main content

​
Submit Result

Submits a new election result block to the blockchain. The block must include valid cryptographic signatures and will be validated before being added to the chain.

​
Request Body

​
hash
string
required
SHA-256 hash of the block header
​
hash_signature
string
required
Cryptographic signature of the block hash
​
merkle_root
array
required
32-byte array representing the Merkle tree root of all results in the block
​
inner
object
required
Block type and data. Can be Genesis, Pending, or Result containing an array of candidate results.
​
height
integer
required
Block height (position in the blockchain)
​
signature_pub_key_hash
string
required
Hash of the validator’s public key
​
timestamp
string
required
ISO 8601 timestamp of block creation
​
prev_hash
string
required
Hash of the previous block in the chain
​
prev_hash_signature
string
required
Signature of the previous block’s hash
​
creator
string
required
Identifier of the node that created this block
​
creator_pub_key
string
required
Public key hash of the block creator
​
version
integer
required
Block format version (currently 1)

​
Response

​
message
string
Confirmation message with the block index

​
Example

cURL
curl -X POST http://localhost:3000/submit \
  -H "Content-Type: application/json" \
  -d '{
    "hash": "a3f5e8d2c1b0...",
    "hash_signature": "304502210...",
    "merkle_root": [12, 45, 78, ...],
    "inner": {
      "Result": [
        {
          "station_id": 1001,
          "candidate_id": 42,
          "votes": 350
        }
      ]
    },
    "height": 125,
    "signature_pub_key_hash": "b2e1c3a4...",
    "timestamp": "2026-03-04T10:30:00Z",
    "prev_hash": "d8c7b6a5...",
    "prev_hash_signature": "304402203...",
    "creator": "node-001",
    "creator_pub_key": "e9f8d7c6...",
    "version": 1
  }'
Response
"Block with index 125 submitted successfully!"

​
Get Block by Height

Retrieve a specific block from the blockchain by its height (block number).

​
Path Parameters

​
height
integer
required
The block height to retrieve (0 for genesis block)

​
Response

​
hash
string
Block hash
​
hash_signature
string
Signature of the block hash
​
merkle_root
array
32-byte Merkle root
​
inner
object
Block type and results data
​
height
integer
Block height
​
signature_pub_key_hash
string
Validator public key hash
​
timestamp
string
Block creation timestamp
​
prev_hash
string
Previous block hash
​
prev_hash_signature
string
Signature of previous block hash
​
creator
string
Block creator identifier
​
creator_pub_key
string
Creator public key hash
​
version
integer
Block format version

​
Example

cURL
curl http://localhost:3000/block/125
Response
{
  "hash": "a3f5e8d2c1b0...",
  "hash_signature": "304502210...",
  "merkle_root": [12, 45, 78, 90, ...],
  "inner": {
    "Result": [
      {
        "station_id": 1001,
        "candidate_id": 42,
        "votes": 350
      },
      {
        "station_id": 1001,
        "candidate_id": 43,
        "votes": 280
      }
    ]
  },
  "height": 125,
  "signature_pub_key_hash": "b2e1c3a4...",
  "timestamp": "2026-03-04T10:30:00Z",
  "prev_hash": "d8c7b6a5...",
  "prev_hash_signature": "304402203...",
  "creator": "node-001",
  "creator_pub_key": "e9f8d7c6...",
  "version": 1
}

​
Block Structure

​
Block Types

Blocks can have one of three types:
  • Genesis - The first block in the chain (height 0)
  • Result - Contains election results data
  • Pending - Placeholder for blocks being constructed

​
Merkle Tree

Each block includes a Merkle root that cryptographically commits to all election results in the block. This allows efficient verification of result integrity without accessing the entire block data.

​
Signatures

Blocks are secured with ECDSA signatures using the P-256 curve. Each block contains:
  • Hash signature: Signature of the block hash by the creator
  • Previous hash signature: Signature of the previous block’s hash
  • Public key hash: SHA-256 hash of the creator’s public key

Build docs developers (and LLMs) love

Get started for freeTalk to us