Skip to content

docs: comprehensive Rholang developer reference#479

Merged
spreston8 merged 1 commit intorust/stagingfrom
docs/rholang-reference
Apr 18, 2026
Merged

docs: comprehensive Rholang developer reference#479
spreston8 merged 1 commit intorust/stagingfrom
docs/rholang-reference

Conversation

@spreston8
Copy link
Copy Markdown
Collaborator

Summary

Adds a comprehensive, verified Rholang developer and AI agent reference under docs/rholang/. 19 topic files organized for both linear reading and targeted lookup. All content is verified against the Rust shard implementation (not inherited from RChain-era Scala docs).

Structure

Fundamentals

  1. Language Overview -- process calculus, names vs processes
  2. Syntax Reference -- complete syntax for all constructs
  3. Data Types -- primitives, strings, byte arrays, URIs
  4. Operators -- arithmetic, comparison, logical, string, interpolation

Types and Collections
5. Pattern Matching -- patterns, connectives, destructuring, type guards
6. Collections -- lists, tuples, sets, maps (all 50 methods verified)
7. PathMaps and Zippers -- hierarchical tries and cursor navigation
8. Numeric Types (file 15) -- Float, BigInt, BigRat, FixedPoint

Concurrency and State
9. Channels and Concurrency -- send/receive, persistent, peek, joins
10. Contracts and State -- cell pattern, CRUD, select, pitfalls

Platform
11. System Channels -- all 28 rho:* URIs with exact arities and calling conventions
12. Registry -- registry operations, TreeHashMap, standard library URIs
13. Vaults and Tokens -- SystemVault, MakeMint, auth keys, transfers
14. Cost Model -- phlogiston accounting with exact formulas from costs.rs

Patterns and Practice
15. Design Patterns -- capability security, ECDSA auth, nonce replay protection, method dispatch, persistent library reference, latest pointer, multi-level TreeHashMap
16. Rhox Macros -- .rhox template format
17. Testing with RhoSpec -- framework reference with real examples
18. Deployment Workflow -- CLI, HTTP, gRPC, WebSocket

Real-World
19. Real-World Applications -- Embers template-based contract generation, deploy flow, data model

Verification

Three verification passes against source code:

  • System channels verified against rholang/src/rust/interpreter/system_processes.rs and rho_runtime.rs
  • All 50 methods verified against reduce.rs method dispatch
  • Cost model verified against rholang/src/rust/interpreter/accounting/costs.rs

Changes

  • Renamed docs/rholang/README.md (crate overview) to crate-overview.md
  • New docs/rholang/README.md is now the index
  • Moved docs/rholang-language-analysis.md into docs/rholang/
  • Preserved legacy RChain-era tutorials (rholangtut.md, rholangmatchingtut.md, ollama.md) with index entries noting they are legacy

Test plan

  • All file links in README resolve
  • All code examples are syntactically valid Rholang
  • System channel URIs match system_processes.rs
  • Method signatures match reduce.rs method_table
  • Cost formulas match costs.rs

19 topic files covering language fundamentals, types, collections,
concurrency, system channels, registry, vaults, cost model, design
patterns, testing, deployment, and real-world application patterns.

All content verified against the Rust shard implementation: 28 system
channels, 50 methods, and exact cost formulas from reduce.rs, costs.rs,
and system_processes.rs.

Co-Authored-By: Claude <noreply@anthropic.com>
@spreston8 spreston8 merged commit 4f1e17a into rust/staging Apr 18, 2026
39 of 40 checks passed
@spreston8 spreston8 deleted the docs/rholang-reference branch April 18, 2026 03:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant