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

[dependencies]
mx-proto = "0.1"

Features

Prost-generated bindings for the MultiversX protocol schemas
bytes::Bytes for protobuf bytes fields to reduce unnecessary copies
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

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:

cargo run --example transaction_roundtrip
cargo run --example outport_decode

Regenerating Bindings

# 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. 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:

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

mx-proto 0.1.0