hotmint-api 0.8.2

JSON-RPC API for external interaction with Hotmint nodes
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

# hotmint-api

[![crates.io](https://img.shields.io/crates/v/hotmint-api.svg)](https://crates.io/crates/hotmint-api)
[![docs.rs](https://docs.rs/hotmint-api/badge.svg)](https://docs.rs/hotmint-api)

JSON-RPC API server for the [Hotmint](https://github.com/rust-util-collections/hotmint) BFT consensus framework.

Provides a TCP-based, newline-delimited JSON-RPC server for querying node status and submitting transactions to the mempool.

## RPC Methods

| Method | Description | Response |
|:-------|:------------|:---------|
| `status` | Query node status (view, height, mempool size) | `StatusInfo` |
| `submit_tx` | Submit a hex-encoded transaction | `TxResult { accepted: bool }` |

## Usage

### Start the Server

```rust
use std::sync::Arc;
use tokio::sync::watch;
use hotmint_mempool::Mempool;
use hotmint_api::rpc::{RpcServer, RpcState};

let mempool = Arc::new(Mempool::default());
let (status_tx, status_rx) = watch::channel((0u64, 0u64, 0u64, 4usize));

use std::sync::{Arc as StdArc, RwLock};
use hotmint_consensus::store::MemoryBlockStore;
use hotmint_consensus::engine::SharedBlockStore;

let store: SharedBlockStore =
    StdArc::new(RwLock::new(Box::new(MemoryBlockStore::new())));
let (_peer_tx, peer_info_rx) = watch::channel(vec![]);

let rpc_state = RpcState {
    validator_id: 0,
    mempool: mempool.clone(),
    status_rx,
    store,
    peer_info_rx,
};

let server = RpcServer::bind("127.0.0.1:26657", rpc_state).await.unwrap();
println!("RPC listening on {}", server.local_addr());
tokio::spawn(async move { server.run().await });
```

### Update Status from Application

```rust
use hotmint_consensus::application::Application;

struct MyApp {
    status_tx: watch::Sender<(u64, u64, u64, usize)>,
}

impl Application for MyApp {
    fn on_commit(&self, block: &hotmint_types::Block, ctx: &hotmint_types::context::BlockContext) -> ruc::Result<()> {
        let _ = self.status_tx.send((
            block.view.as_u64(),
            block.height.as_u64(),
            ctx.epoch.as_u64(),
            ctx.validator_set.validator_count(),
        ));
        Ok(())
    }
}
```

### Client Examples

```bash
# query status
echo '{"method":"status","params":{},"id":1}' | nc 127.0.0.1 26657
# => {"result":{"validator_id":0,"current_view":42,"last_committed_height":15,"mempool_size":3},...}

# submit transaction (hex-encoded, bare string in params)
echo '{"method":"submit_tx","params":"deadbeef","id":2}' | nc 127.0.0.1 26657
# => {"result":{"accepted":true},...}
```

## Types

```rust
pub struct RpcRequest  { pub method: String, pub params: Value, pub id: u64 }
pub struct RpcResponse { pub result: Option<Value>, pub error: Option<RpcError>, pub id: u64 }
pub struct RpcError    { pub code: i32, pub message: String }
pub struct StatusInfo  { pub validator_id: u64, pub current_view: u64, pub last_committed_height: u64, pub mempool_size: usize }
pub struct TxResult    { pub accepted: bool }
```

## License

GPL-3.0-only