@wireio/protoc-gen-solana 1.0.1 → 1.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +143 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
# protoc-gen-solana
|
|
2
|
+
|
|
3
|
+
A `protoc` plugin that generates Rust protobuf encode/decode modules from proto3 definitions, optimized for Solana programs.
|
|
4
|
+
|
|
5
|
+
Given a `.proto` file, the plugin outputs:
|
|
6
|
+
|
|
7
|
+
- A `.pb.rs` file per proto file containing Rust structs with `encode()` / `decode()` methods
|
|
8
|
+
- A shared `protobuf_runtime.rs` with wire format primitives (varint, fixed, zigzag, length-delimited)
|
|
9
|
+
|
|
10
|
+
Generated code targets minimal allocations and efficient compute, suitable for Solana's on-chain constraints.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install @wireio/protoc-gen-solana
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Requires Node >= 24 and `protoc` on your PATH.
|
|
19
|
+
|
|
20
|
+
## Usage
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
protoc \
|
|
24
|
+
--plugin=protoc-gen-solana=./node_modules/.bin/protoc-gen-solana \
|
|
25
|
+
--solana_out=./generated \
|
|
26
|
+
path/to/your.proto
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
### Plugin Parameters
|
|
30
|
+
|
|
31
|
+
Pass parameters via `--solana_opt`:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
protoc --solana_opt=log_level=debug ...
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
| Parameter | Values | Default |
|
|
38
|
+
|-------------|-------------------------------------------------|---------|
|
|
39
|
+
| `log_level` | `log`, `trace`, `debug`, `info`, `warn`, `error` | `info` |
|
|
40
|
+
|
|
41
|
+
## Example
|
|
42
|
+
|
|
43
|
+
Given this proto:
|
|
44
|
+
|
|
45
|
+
```proto
|
|
46
|
+
syntax = "proto3";
|
|
47
|
+
package example;
|
|
48
|
+
|
|
49
|
+
message SolanaAccount {
|
|
50
|
+
bytes pubkey = 1;
|
|
51
|
+
uint64 lamports = 2;
|
|
52
|
+
bytes owner = 3;
|
|
53
|
+
bool executable = 4;
|
|
54
|
+
uint64 rent_epoch = 5;
|
|
55
|
+
bytes data = 6;
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The plugin generates a Rust struct:
|
|
60
|
+
|
|
61
|
+
```rust
|
|
62
|
+
use crate::protobuf_runtime::*;
|
|
63
|
+
|
|
64
|
+
#[derive(Clone, Debug, Default, PartialEq)]
|
|
65
|
+
#[cfg_attr(feature = "borsh", derive(borsh::BorshSerialize, borsh::BorshDeserialize))]
|
|
66
|
+
pub struct SolanaAccount {
|
|
67
|
+
pub pubkey: Vec<u8>,
|
|
68
|
+
pub lamports: u64,
|
|
69
|
+
pub owner: Vec<u8>,
|
|
70
|
+
pub executable: bool,
|
|
71
|
+
pub rent_epoch: u64,
|
|
72
|
+
pub data: Vec<u8>,
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
impl SolanaAccount {
|
|
76
|
+
pub fn encode(&self) -> Vec<u8> { /* ... */ }
|
|
77
|
+
pub fn decode(data: &[u8]) -> Result<Self, DecodeError> { /* ... */ }
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Supported Proto3 Features
|
|
82
|
+
|
|
83
|
+
| Feature | Rust Representation |
|
|
84
|
+
|---|---|
|
|
85
|
+
| Scalar types (int32, uint64, bool, string, bytes, float, double, etc.) | Native Rust types (`i32`, `u64`, `bool`, `String`, `Vec<u8>`, `f32`, `f64`) |
|
|
86
|
+
| Nested messages | Struct with `encode()`/`decode()` |
|
|
87
|
+
| Repeated fields | `Vec<T>` |
|
|
88
|
+
| Map fields | Parallel `Vec<K>` + `Vec<V>` (keys and values) |
|
|
89
|
+
| Enums | `i32` |
|
|
90
|
+
| sint32 / sint64 | ZigZag-encoded `i32` / `i64` |
|
|
91
|
+
| fixed32 / fixed64 / sfixed32 / sfixed64 | Fixed-width encoding |
|
|
92
|
+
| Unknown fields | Silently skipped during decode |
|
|
93
|
+
| Borsh serialization | Opt-in via `feature = "borsh"` on the generated crate |
|
|
94
|
+
|
|
95
|
+
### Map Field Convention
|
|
96
|
+
|
|
97
|
+
Proto map fields are represented as parallel vectors rather than `HashMap`, keeping serialization efficient for Solana:
|
|
98
|
+
|
|
99
|
+
```proto
|
|
100
|
+
map<string, string> metadata = 8;
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
becomes:
|
|
104
|
+
|
|
105
|
+
```rust
|
|
106
|
+
pub metadata_keys: Vec<String>,
|
|
107
|
+
pub metadata_values: Vec<String>,
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
## Generated File Layout
|
|
111
|
+
|
|
112
|
+
For a proto file `path/to/service.proto` with `package example.nested`:
|
|
113
|
+
|
|
114
|
+
```
|
|
115
|
+
<output_dir>/
|
|
116
|
+
protobuf_runtime.rs # Always emitted — shared wire format primitives
|
|
117
|
+
example/nested/service.pb.rs # Per-proto generated structs
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
The generated code imports the runtime via `use crate::protobuf_runtime::*;`, so both files should live in the same Rust crate.
|
|
121
|
+
|
|
122
|
+
## Development
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
pnpm install
|
|
126
|
+
pnpm dev # Watch mode (TypeScript compile + esbuild bundle)
|
|
127
|
+
pnpm dist # Full production build (compile + bundle + pkg binary)
|
|
128
|
+
pnpm format # Format source with prettier
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### Testing
|
|
132
|
+
|
|
133
|
+
```bash
|
|
134
|
+
pnpm generate:test
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
This builds the plugin binary and runs `protoc` against the proto files in `tests/protos/`, writing generated Rust output to `dist/tests/generated/`.
|
|
138
|
+
|
|
139
|
+
The Rust runtime (`rs/protobuf_runtime.rs`) contains `#[cfg(test)]` unit tests covering all wire format primitives.
|
|
140
|
+
|
|
141
|
+
## License
|
|
142
|
+
|
|
143
|
+
See [LICENSE](LICENSE) for details.
|
package/package.json
CHANGED