Skip to content

Commit 60e4851

Browse files
dannywillemsdannywillems
committed
Add mina-tx-type crate with coinbase transaction types
This adds a new standalone crate that provides Mina Protocol transaction types for external use without requiring the full ledger crate. Extracted types and traits: - Sgn enum (sign type) - Magnitude trait (numeric operations) - MinMax trait (bounds) - Signed<T> struct (signed magnitude wrapper) - Amount and Fee types (via impl_number! macro) - Coinbase and CoinbaseFeeTransfer structs The extraction excludes proof-related code (to_field, of_field, etc.) to keep the crate lightweight. The ledger crate continues to use its own implementations. Closes #1824
1 parent 420921b commit 60e4851

File tree

7 files changed

+1185
-0
lines changed

7 files changed

+1185
-0
lines changed

‎Cargo.lock‎

Lines changed: 8 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Cargo.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ members = [
2727
"tools/ledger-tool",
2828
"tools/transport",
2929
"tools/webrtc-sniffer",
30+
"mina-tx-type",
3031
"vendor/salsa-simple",
3132
"vrf",
3233
]
@@ -147,6 +148,7 @@ mina-p2p-messages = { path = "mina-p2p-messages" }
147148
mina-poseidon = { git = "https://github.com/o1-labs/proof-systems", tag = "0.2.0" }
148149
mina-signer = { git = "https://github.com/o1-labs/proof-systems", tag = "0.2.0" }
149150
mina-transport = { path = "tools/transport" }
151+
mina-tx-type = { path = "mina-tx-type" }
150152
mio = { version = "1.0.4", features = ["os-poll", "net"] }
151153
multiaddr = "0.18.1"
152154
multihash = { version = "0.18.1", features = ["blake2b"] }

‎mina-tx-type/Cargo.toml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
[package]
2+
name = "mina-tx-type"
3+
version = "0.18.1"
4+
edition = "2021"
5+
license = "Apache-2.0"
6+
description = "Transaction types for the Mina Protocol"
7+
8+
[dependencies]
9+
mina-signer = { workspace = true }
10+
serde = { workspace = true, features = ["derive"] }

‎mina-tx-type/EXTRACTION_ANALYSIS.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# Coinbase Type Extraction Analysis
2+
3+
This document analyzes the types, traits, and macros that would need to be moved
4+
to extract coinbase transaction types into the `mina-tx-type` crate.
5+
6+
## Overview
7+
8+
The coinbase types (`Coinbase`, `CoinbaseFeeTransfer`) depend on currency types
9+
(`Amount`, `Fee`) which are generated by a macro and implement several traits
10+
with deep dependencies on proof-related code.
11+
12+
## Macros Used for Currency Types
13+
14+
### `impl_number!` Macro
15+
16+
Location: `ledger/src/scan_state/currency.rs:382-573`
17+
18+
This is the **only macro** used to implement the currency types. It's a
19+
two-level macro:
20+
21+
**Invocation (line 575-578):**
22+
23+
```rust
24+
impl_number!(
25+
32: { Length, Slot, Nonce, Index, SlotSpan, TxnVersion, Epoch, },
26+
64: { Amount, Balance, Fee, BlockTime, BlockTimeSpan, N, },
27+
);
28+
```
29+
30+
**What it generates for each type:**
31+
32+
| Generated Item | Description |
33+
| --------------------------------- | -------------------------------------------------------------------------------------------------------- |
34+
| `struct $name(pub(super) $inner)` | Newtype wrapper around u32 or u64 |
35+
| `impl Debug` | Custom debug formatting |
36+
| `impl Magnitude` | All numeric operations trait |
37+
| `impl MinMax` | Min/max value trait |
38+
| Inherent methods | `as_u64()`, `from_u64()`, `scale()`, `min()`, `max()`, `of_mina_string_exn()`, `to_bits()`, `to_field()` |
39+
| `impl Distribution<$name>` | Random number generation |
40+
| `impl ToInputs` | Poseidon hash inputs |
41+
| `impl ToFieldElements<F>` | Field element conversion |
42+
| `impl Check<F>` | Proof witness checking |
43+
44+
**Derives (line 388):**
45+
46+
```rust
47+
#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, serde::Deserialize, serde::Serialize)]
48+
```
49+
50+
## Manually Implemented Types (No Macros)
51+
52+
### `Sgn` Enum (lines 11-38)
53+
54+
```rust
55+
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
56+
pub enum Sgn { Pos, Neg }
57+
```
58+
59+
Manual implementations:
60+
61+
- `is_pos()` - Check if positive
62+
- `negate()` - Flip sign
63+
- `to_field()` - Convert to field element (proof-related)
64+
65+
### `Magnitude` Trait (lines 40-70)
66+
67+
Manually defined trait with:
68+
69+
- **Constants:** `NBITS`
70+
- **Required methods:** `abs_diff`, `wrapping_add`, `wrapping_mul`,
71+
`wrapping_sub`, `checked_add`, `checked_mul`, `checked_sub`, `checked_div`,
72+
`checked_rem`, `is_zero`, `zero`, `to_field`, `of_field`
73+
- **Default methods:** `add_flagged`, `sub_flagged`
74+
75+
### `MinMax` Trait (lines 72-76)
76+
77+
Simple trait with `min()` and `max()` methods.
78+
79+
### `Signed<T>` Struct (lines 78-205)
80+
81+
```rust
82+
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
83+
pub struct Signed<T: Magnitude> {
84+
pub magnitude: T,
85+
pub sgn: Sgn,
86+
}
87+
```
88+
89+
- Generic over any `Magnitude` type
90+
- Manual implementations: `create`, `of_unsigned`, `negate`, `is_pos`, `is_neg`,
91+
`zero`, `is_zero`, `add`, `add_flagged`, `gen`
92+
- Specialized impl for `Signed<Amount>::to_fee()`
93+
94+
### Type-Specific Implementations (lines 207-380)
95+
96+
Additional methods for specific types (not generated by macro):
97+
98+
| Type | Additional Methods |
99+
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
100+
| `Amount` | `of_fee()`, `add_signed_flagged()`, `to_nanomina_int()`, `to_mina_int()`, `of_mina_int_exn()`, `of_nanomina_int_exn()` |
101+
| `Balance` | `sub_amount()`, `add_amount()`, `add_signed_flagged()`, `add_signed_amount_flagged()`, `to_amount()`, `from_mina()`, `of_nanomina_int_exn()` |
102+
| `Fee` | `of_nanomina_int_exn()` |
103+
| `Index` | `incr()` |
104+
| `Nonce` | `incr()`, `succ()`, `add_signed_flagged()`, `between()` |
105+
| `BlockTime` | `add()`, `sub()`, `diff()`, `to_span_since_epoch()`, `of_span_since_epoch()`, `From<BlockTimeTimeStableV1>` |
106+
| `BlockTimeSpan` | `of_ms()`, `to_ms()` |
107+
| `Slot` | `incr()`, `add()`, `succ()`, `gen_small()` |
108+
109+
## External Dependencies in the Macro
110+
111+
The macro references these external items:
112+
113+
| Dependency | Used In | From |
114+
| ------------------------------------- | ---------------------------------------------------------- | ---------------------------------------------- |
115+
| `ark_ff::BigInteger256` | `of_field()` | ark-ff crate |
116+
| `ark_ff::Field` | `to_field()` | ark-ff crate |
117+
| `FieldWitness` | `Magnitude::to_field/of_field`, `ToFieldElements`, `Check` | `crate::proofs::field` |
118+
| `ToFieldElements<F>` | trait impl | `crate::proofs::to_field_elements` |
119+
| `Check<F>` | trait impl | `crate::proofs::transaction` |
120+
| `Witness<F>` | `Check::check()` | `crate::proofs::witness` |
121+
| `poseidon::hash::Inputs` | `ToInputs` | poseidon crate |
122+
| `bits_iter` | `to_bits()` | `crate::proofs::transaction::legacy_input` |
123+
| `to_field_checked_prime` | `Check::check()` | `crate::proofs::transaction::scalar_challenge` |
124+
| `rand::Rng`, `rand::distributions::*` | random generation | rand crate |
125+
126+
## Types Required for Complete Coinbase Extraction
127+
128+
### Tier 1: Core Types (Minimum Required)
129+
130+
| Type | Location | Description |
131+
| --------------------- | ---------------------------------- | ------------------------------ |
132+
| `Coinbase` | `transaction_logic/mod.rs:437-541` | Block reward transaction |
133+
| `CoinbaseFeeTransfer` | `transaction_logic/mod.rs:415-432` | Fee transfer to SNARK worker |
134+
| `Amount` | `currency.rs` (via macro) | Currency amount (u64 wrapper) |
135+
| `Fee` | `currency.rs` (via macro) | Transaction fee (u64 wrapper) |
136+
| `CompressedPubKey` | `mina_signer` (external) | Already in `mina-signer` crate |
137+
138+
### Tier 2: Types Used in Coinbase Methods
139+
140+
| Type | Location | Used By |
141+
| ------------------- | -------------------------- | --------------------------------------------------------- |
142+
| `AccountId` | `account/account.rs:1022` | `Coinbase::receiver()`, `Coinbase::accounts_referenced()` |
143+
| `TokenId` | `account/account.rs:50` | Part of `AccountId` |
144+
| `FeeExcess` | `fee_excess.rs` | `Coinbase::fee_excess()` |
145+
| `TransactionStatus` | `transaction_logic/mod.rs` | `Coinbase::account_access_statuses()` |
146+
| `AccessedOrNot` | `zkapp_command/mod.rs` | `Coinbase::account_access_statuses()` |
147+
148+
### Tier 3: Traits and Supporting Types
149+
150+
| Type/Trait | Location | Description |
151+
| -------------------- | --------------------- | ------------------------------------ |
152+
| `Magnitude` | `currency.rs:40-70` | Core trait for numeric operations |
153+
| `Sgn` | `currency.rs:11-38` | Sign enum (Pos/Neg) |
154+
| `Signed<T>` | `currency.rs:78-205` | Generic signed magnitude type |
155+
| `MinMax` | `currency.rs:72-76` | Min/max value trait |
156+
| `impl_number!` macro | `currency.rs:382-578` | Generates Amount/Fee implementations |
157+
158+
### Tier 4: Conversion Types (From P2P Messages)
159+
160+
| Type | Location | Notes |
161+
| -------------------------------- | ------------------- | ------------------------------------- |
162+
| `MinaBaseCoinbaseStableV1` | `mina-p2p-messages` | Keep `From`/`TryFrom` impls in ledger |
163+
| `StagedLedgerDiffDiffFtStableV1` | `mina-p2p-messages` | For CoinbaseFeeTransfer conversions |
164+
165+
## Extraction Strategy
166+
167+
For a minimal extraction to `mina-tx-type`, you would need to:
168+
169+
### Move without proof dependencies
170+
171+
- `Sgn` enum (simple)
172+
- `Magnitude` trait (simplified, without `to_field`/`of_field`)
173+
- `MinMax` trait (simple)
174+
- `Signed<T>` struct (without `gen()`)
175+
- Simplified `impl_number!` macro (without proof-related impls)
176+
- `Amount` and `Fee` types with basic operations
177+
178+
### Keep in ledger
179+
180+
- `ToFieldElements`, `Check`, `ToInputs` implementations
181+
- `to_field()`, `of_field()`, `to_bits()` methods
182+
- All proof-related code
183+
- `From`/`TryFrom` implementations for p2p message types
184+
- Methods returning `AccountId`, `FeeExcess`, `TransactionStatus`
185+
186+
## Current Implementation
187+
188+
The current `mina-tx-type` crate provides standalone types with simplified
189+
`Amount` and `Fee` implementations that don't depend on the proof system. The
190+
ledger crate continues to define its own tightly-integrated versions.
191+
192+
This approach allows external projects to use the transaction types without
193+
pulling in the full proof system dependencies, while the ledger crate maintains
194+
full functionality for block validation and proof generation.
195+
196+
## Related Issues
197+
198+
- [#1665](https://github.com/o1-labs/mina-rust/issues/1665) - Extract
199+
transaction types into a crate (parent issue)
200+
- [#1824](https://github.com/o1-labs/mina-rust/issues/1824) - Extract coinbase
201+
transaction types into mina-tx-type crate
202+
- [#1825](https://github.com/o1-labs/mina-rust/issues/1825) - Extract fee
203+
transfer transaction types
204+
- [#1826](https://github.com/o1-labs/mina-rust/issues/1826) - Extract signed
205+
command types
206+
- [#1827](https://github.com/o1-labs/mina-rust/issues/1827) - Extract zkApp
207+
command types

0 commit comments

Comments
 (0)