| name | rust-blockchain-guide |
| description | Use when building Rust blockchain programs (Solana, Substrate/Polkadot, NEAR, Cosmos SDK, Stacks). Covers account model architecture, program-derived addresses (PDA), BPF bytecode constraints, no_std + Solana hybrid, Substrate FRAME pallets, cross-program invocation (CPI), and deterministic transaction execution. Vertical deepening of rust-architecture-guide for blockchain and Web3. |
| metadata | {"version":"1.0.0","philosophy":"Determinism, Account Model, Verifiable Compute, Jeet Kune Do","domain":"blockchain & Web3","relationship":"vertical-deepening-of:[rust-architecture-guide, rust-embedded-iot-guide]","default_edition":"2024","supported_editions":["2021","2024"],"aligned_with":["Solana BPF constraints","Substrate FRAME","Anchor framework","SPL Token standard"],"note":"Scope covers Solana programs and Substrate pallets. Cosmos SDK and Stacks are mentioned in description but not covered in depth."} |
Rust Blockchain & Web3 Guide V1.0.0
Vertical deepening of rust-architecture-guide and rust-embedded-iot-guide for blockchain programs (smart contracts). Assumes deterministic execution, verifiable compute, and hard resource constraints (BPF bytecode, gas metering).
Core Philosophy
| Principle | Description |
|---|
| Determinism | Every transaction must produce identical state on every validator. Same inputs → same outputs. |
| Account Model | State is partitioned into accounts. Programs are stateless. Data lives in accounts. |
| Verifiable Compute | Every program execution must be reproducible. Gas metering bounds compute. |
| Jeet Kune Do | One-pass transaction processing. Anchor constraints fold validation + execution into one derive. |
Action 1: Account Model & State Partitioning
Blockchain state is an account database, not a traditional database.
- Solana: Programs are stateless. Accounts hold state.
AccountInfo with data: Rc<RefCell<&mut [u8]>>.
- Substrate: FRAME pallets with
StorageMap/StorageValue. Merkle-Patricia trie backend.
- Account Serialization:
borsh (Solana), parity-scale-codec (Substrate), borsh (NEAR)
- Red Line: Programs must not store state internally. All state must be in accounts.
→ references/01-account-model.md
Action 2: Program Derived Addresses (PDA)
PDAs are deterministic addresses derived from seeds + program ID. No private key.
Pubkey::find_program_address(&[seeds], &program_id): Deterministic derivation- Bump Seed: PDAs are off the ed25519 curve. Bump seed ensures address security.
- Use Cases: Escrow accounts, vaults, authority delegation, state compression
- Red Line: PDA seeds must include unique identifiers (user pubkey, nonce). Collision = drained account.
→ references/02-pda.md
Action 3: BPF Bytecode Constraints & no_std Hybrid
Solana programs compile to BPF (Berkeley Packet Filter) bytecode, not native machine code.
- BPF Constraints: No
std (use solana-program). 200KB max program size. 200K CU budget.
- No Floating Point: BPF has no native f64/f32. Use fixed-point arithmetic (
u64 with 9 decimals).
- No Dynamic Dispatch: No
Box<dyn Trait>, no Rc, no Arc. Static dispatch only.
- Red Line: Program size and compute unit limits are chain-specific and evolve. Verify current limits from the target chain's official documentation at build time. (Solana historically ~200KB program, ~200K CU; Substrate weight varies by runtime.)
→ references/03-bpf-constraints.md
Action 4: Anchor Framework & Program Structure
Anchor is the standard Solana framework. Derive macros reduce boilerplate by 90%.
#[program]: Defines program entry point. pub mod my_program { ... }#[derive(Accounts)]: Instruction account validation struct. #[account(mut)], #[account(signer)]#[account]: Account data struct. #[derive(InitSpace)] for space calculation + discriminator.- Red Line: Every instruction must validate all accounts via
#[derive(Accounts)]. Never skip.
→ references/04-anchor-framework.md
Action 5: Cross-Program Invocation (CPI)
Programs call other programs. Token transfers, AMM swaps, oracle queries.
- CPI:
invoke(&instruction, &[account_infos]) or invoke_signed() for PDA authority
- Token Standard: SPL Token program.
transfer(), mint_to(), burn(). Use anchor_spl.
- Program Composability: Check program ownership (
account.owner == expected_program_id)
- Red Line: CPI calls must check return values. Silent failures = drained vaults.
→ references/05-cpi.md
Action 6: Substrate FRAME Pallets
For Polkadot/Substrate chains, FRAME is the standard framework.
- Pallets:
#[frame::pallet] module. #[pallet::storage], #[pallet::call], #[pallet::event].
- Weights: Benchmark each extrinsic.
#[pallet::weight(T::WeightInfo::my_func())].
- Runtime:
construct_runtime! macro assembles pallets into a chain.
- Red Line: Unbounded weight → block full. All extrinsics must have benchmark-derived weights.
→ references/06-substrate-pallets.md
Action 7: Token Economics & SPL Standards
Token programs follow standardized interfaces.
- SPL Token: Fungible token standard. Mint, account, transfer, approve.
- SPL Token-2022: Extended token with transfer fees, confidential transfers, metadata.
- SPL Associated Token Account (ATA): Deterministic PDA for user token accounts
- Red Line: Token arithmetic overflow → catastrophic loss. Use
checked_add/checked_sub or u64.
→ references/07-token-economics.md
Action 8: Security & Auditing
Blockchain programs handle real money. Security is P0.
- Reentrancy: Never CPI to untrusted program after state mutation. Checks-Effects-Interactions.
- Integer Overflow: Use
checked_* math. overflow-checks = true in release (Solana default).
- Access Control: Every instruction must verify signer authority.
#[account(signer)] on Anchor.
- Fuzzing:
trident framework for Solana program fuzzing. cargo-fuzz for parser/deserializer.
- Red Line: Programs holding significant value on mainnet must undergo third-party security audit. Testnet and internal deployments do not require full audit.
→ references/08-security.md
Prohibitions Quick List
| Category | Prohibited | Mandatory |
|---|
| State | Internal program state | Account-based state (#[account]) |
| Arithmetic | Unchecked +/-/* | checked_add/checked_sub/checked_mul |
| Reentrancy | CPI after state mutation | Checks-Effects-Interactions pattern |
| BPF | Floating point (f32/f64) | Fixed-point u64 with decimal scaling |
| BPF | Dynamic dispatch (Box<dyn>/Rc) | Static dispatch only |
| Accounts | Unvalidated instruction accounts | #[derive(Accounts)] validation |
| CPI | Unchecked return values | Verify invoke() result |
| PDA | Predictable seeds | Include unique identifiers, bump seed |
| Weights | Unbounded extrinsic weight | Benchmark-derived #[pallet::weight] |
| Security | Unaudited mainnet program with significant value | Third-party audit + formal verification |
Document Relationship Map
flowchart TD
subgraph Foundation["rust-architecture-guide + embedded-iot-guide"]
P0[P0 Safety]
NoStd[01-no-std-architecture.md]
Consensus[04-consensus.md]
end
subgraph Chain["rust-blockchain-guide"]
Account[01-account-model.md]
PDA[02-pda.md]
BPF[03-bpf-constraints.md]
Anchor[04-anchor-framework.md]
CPI[05-cpi.md]
Substrate[06-substrate-pallets.md]
Token[07-token-economics.md]
Security[08-security.md]
end
P0 -->|hardens| Security
NoStd -->|adapts| BPF
Consensus -->|determinism| Account
Account --> PDA
Account --> Anchor
BPF --> Anchor
Anchor --> CPI
Anchor --> Token
CPI --> Security
Account --> Substrate
style Account fill:#d9534f,stroke:#c9302c,color:#fff
style BPF fill:#5cb85c,stroke:#4cae4c,color:#fff
style Anchor fill:#f0ad4e,stroke:#ec971f,color:#000
Reference Files
| File | Topic | Key Directive |
|---|
| 01-account-model.md | Account Model & State Partitioning | Solana/Substrate account architecture, serialization |
| 02-pda.md | Program Derived Addresses | Deterministic derivation, bump seeds, use cases |
| 03-bpf-constraints.md | BPF & no_std Constraints | CU budget, no float, static dispatch only |
| 04-anchor-framework.md | Anchor Framework | #[program], #[derive(Accounts)], #[account] |
| 05-cpi.md | Cross-Program Invocation | invoke(), invoke_signed(), SPL Token CPI |
| 06-substrate-pallets.md | Substrate FRAME Pallets | #[frame::pallet], storage, weights, construct_runtime |
| 07-token-economics.md | Token Economics & SPL | SPL Token/Token-2022, ATA, arithmetic safety |
| 08-security.md | Security & Auditing | Reentrancy, overflow, access control, trident fuzzing |
Changelog
V1.0.0
- Initial framework: account model (Solana + Substrate), PDA derivation, BPF constraints
- Anchor framework with #[derive(Accounts)] validation and #[account] data
- Cross-Program Invocation (CPI) with SPL Token standard
- Substrate FRAME pallets, weights benchmarking, construct_runtime
- Security: reentrancy prevention, checked math, access control, trident fuzzing
- Aligned with rust-architecture-guide V9.1.0 and rust-embedded-iot-guide V1.0.0
