mx-proto 0.1.1

Protobuf and gRPC bindings for MultiversX network protocols.
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
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

# mx-proto

Protobuf and gRPC bindings for MultiversX network protocols.

`mx-proto` packages the generated bindings, gRPC stubs, and a few convenience
helpers that are commonly needed by downstream MultiversX services.

## Install

```toml
[dependencies]
mx-proto = "0.1"
```

Enable gRPC stubs only when you need them:

```toml
[dependencies]
mx-proto = { version = "0.1", features = ["tonic"] }
```

## Features

- Prost-generated bindings for the MultiversX protocol schemas
- `bytes::Bytes` for protobuf `bytes` fields to reduce unnecessary copies
- Optional `tonic` client and server stubs for gRPC services
- Helpers for transaction hashing and Bech32 address formatting
- Re-export of `prost::Message` for encoding and decoding ergonomics

## What Users Get

- Generated protobuf messages under `mx_proto::generated::*`
- The main schema set under `mx_proto::generated::proto::*`
- Additional generated modules such as storage and VM host bindings
- Manual helpers on `Transaction` for canonical hashing and Bech32 address formatting

## Usage

```rust
use mx_proto::{
    Message,
    generated::proto::{Batch, Transaction},
};

let tx = Transaction {
    nonce: 1,
    snd_addr: vec![0x11; 32].into(),
    rcv_addr: vec![0x22; 32].into(),
    ..Default::default()
};

let tx_bytes = tx.encode_to_vec();
let hash = tx.get_tx_hash();
let sender = tx.sender_bech32()?;
let receiver = tx.receiver_bech32()?;

let batch = Batch {
    data: vec![tx_bytes.into()],
    ..Default::default()
};
let batch_bytes = batch.encode_to_vec();
let decoded = Batch::decode(batch_bytes.as_slice())?;

assert_eq!(decoded.data.len(), 1);
assert_eq!(hash.len(), 32);
assert!(sender.is_some());
assert!(receiver.is_some());
# Ok::<(), Box<dyn std::error::Error>>(())
```

## Examples

The packaged examples are intended to work even when the repository itself is
private:

```bash
cargo run --example transaction_roundtrip
cargo run --example outport_decode
```

## Regenerating Bindings

```bash
# Build the crate inside the workspace to regenerate the bindings from
# ../../proto/raw into Cargo's OUT_DIR.
cargo build -p mx-proto
```

Published crates and docs.rs builds use the checked-in generated bindings under
`generated/`. Workspace builds prefer regenerating from the raw schema files in
`../../proto/raw` when they are available.

## docs.rs

The public documentation is intended to live on [docs.rs](https://docs.rs/mx-proto).
Because this crate ships checked-in generated bindings, docs.rs builds do not
need access to the private workspace repository layout in order to succeed.

## Included Schemas

The workspace raw schemas live under `../../proto/raw/` and include:
- `transaction.proto` - Transaction structure
- `block.proto` - Block and miniblock structures
- `heartbeat.proto` - Validator heartbeat messages

## Maintainer Release Flow

The repository includes a manual GitHub Actions workflow for publishing the
crate. The expected maintainer flow is:

1. Sync `proto/raw` with the upstream Go schema sources.
2. Run `cargo test -p mx-proto`.
3. Run `cargo publish -p mx-proto --dry-run`.
4. Trigger the publish workflow or publish locally with a crates.io token.