Skip to main content

​
Overview

Submitting results creates a new block containing election data from a polling station. Each submission is cryptographically signed and includes a Merkle root for efficient verification.

​
Submit Command

The basic submit command sends results to a submission node: 
ubu-block --config config.toml submit <node_addr> <station_id> <candidate_id> <votes>

​
Parameters

  • node_addr: The HTTP address of the submission node (e.g., http://localhost:8080)
  • station_id: Unique identifier for the polling station
  • candidate_id: Unique identifier for the candidate
  • votes: Number of votes received

​
Example Usage

1

Submit first candidate's results

Submit results for candidate 1 at polling station 022113056303301:
ubu-block --config config.toml submit http://localhost:8080 022113056303301 1 66
2

Submit second candidate's results

Submit results for candidate 2 at the same station:
ubu-block --config config.toml submit http://localhost:8080 022113056303301 2 21
3

Verify submission

On successful submission, you’ll see:
Block submitted successfully
Each submission creates a new block in the blockchain. Multiple results can be included in a single block by extending the implementation.

​
How Submission Works

When you submit results, the following process occurs:

​
1. Block Creation

The CLI creates a new block containing: 
CandidateResult {
    station_id: 022113056303301,
    candidate_id: 1,
    votes: 66
}

​
2. Merkle Tree Generation

A Merkle tree is constructed from the election results, providing:
  • Efficient verification of individual results
  • Tamper-evident data structure
  • Root hash included in the block

​
3. Digital Signature

The block is signed using your node’s private key:
  • Ensures authenticity of the submission
  • Links the block to your node’s identity
  • Prevents repudiation

​
4. HTTP Submission

The signed block is sent to the submission node via HTTP POST: 
POST /submit HTTP/1.1
Host: localhost:8080
Content-Type: application/json

{
  "height": 2,
  "prev_hash": "0e70cebe...",
  "creator": "genesis",
  "signature": "a3f5b2...",
  "results": [...]
}

​
Submission Nodes

Submission nodes are specialized nodes that:
  • Accept result submissions from authorized users
  • Validate block structure and signatures
  • Propagate accepted blocks to the P2P network
  • Maintain an audit trail of all submissions

​
Running a Submission Node

To run your own submission node: 
ubu-block --config config.toml serve --port 8080
Submission nodes should implement authorization to prevent spam. Future versions will include access control mechanisms.

​
Block Structure

Each submitted block contains:
FieldDescription
heightSequential block number
prev_hashHash of the previous block
creatorPublic key hash of block creator
creator_pub_keyFull public key for verification
signatureDigital signature of block contents
signature_pub_key_hashHash of signing public key
merkle_rootRoot hash of results Merkle tree
resultsArray of candidate results
timestampBlock creation time
hashHash of entire block

​
Validation and Consensus

Submitted blocks undergo validation:
  1. Structure Validation: Correct format and required fields
  2. Signature Verification: Valid signature from known public key
  3. Chain Continuity: Correct previous hash and height
  4. Result Validation: Valid station and candidate IDs
  5. Merkle Verification: Results match Merkle root

​
Error Handling

​
Common Errors

Failed to submit block: 400 The submission node rejected your block. Possible reasons:
  • Invalid signature
  • Incorrect previous hash
  • Malformed results data
Error submitting block: Connection refused The submission node is not reachable:
  • Verify the node address
  • Ensure the node is running
  • Check network connectivity
Invalid station_id or candidate_id The IDs don’t exist in the initialized database:
  • Verify IDs match your setup SQL
  • Check for typos in the command

​
Best Practices

While the current implementation submits one result at a time, future versions will support batching multiple results into a single block for efficiency.
Double-check vote counts before submission. Blockchain immutability means corrections require new blocks.
Your private database contains signing keys. Protect it:
  • Restrict file permissions
  • Regular backups
  • Never commit to version control
Wait for confirmation before considering a submission successful. Network delays may occur.

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us