Contractless/docs/DEV.md

Contractless Developer Guide

Contractless builds as both executable tools and a Rust library crate named blockchain. The library artifact is libblockchain.rlib, and it exposes the same major modules used by the node, CLI tools and internal tests.

This file is a developer map. It is not meant to replace generated Rust documentation. Many functions are public because the crate is split across modules, not because every public function is a stable external API.

Build Targets

The package builds node binaries, standalone CLI tools and the blockchain library crate.

Default testnet build:

cargo build --release

Explicit testnet build:

cargo build --release --features testnet

Mainnet has a feature flag, but mainnet builds are disabled during the testnet phase:

cargo build --release --no-default-features --features mainnet

Generated API Reference

Use Rustdoc for the complete list of public modules, structs, enums, constants and functions:

cargo doc --no-deps

Open the generated reference:

target/doc/blockchain/index.html

The generated docs are the best way to inspect every exposed item in libblockchain.rlib.

Public Surface

The crate root exposes these local modules:

Module	What it contains
blocks	Block structs, transaction structs, byte encoding and transaction balance effects
common	Shared constants, hashing, settings paths, CLI prompts, network startup helpers and shared utility code
config	settings.ini loading and Settings structure
miner	Mining loop, nonce search, block reward logic, fairness checks and mining structs
orphans	Orphan correction, rollback, staged torrent replay and transaction undo logic
records	Chain records, balance sheets, wallet registry, memory records, PostgreSQL helpers and network mappings
rpc	RPC command IDs, client helpers, server loop, command handlers and response types
standalone_tools	Shared connection and request helpers used by CLI tools
startup	Node startup, daemon/service support, logging, paths and runtime initialization
torrent	Torrent metadata, torrent cache, torrent staging, block download and torrent validation
verifications	Transaction, block, torrent and rule validation logic
wallets	Wallet structs, address conversion, key generation, signing, verification and vanity lookup

The crate root also re-exports many dependency types and functions used throughout the project. This keeps internal modules consistent, but external developers should prefer the stable public modules above instead of relying on dependency re-exports as an API contract.

Useful Entry Points

Wallets

Useful for tools that need to load wallets, derive addresses or sign data.

Common areas:

• wallets::structures::Wallet
• wallets::structures::SavedWallet
• address conversion functions in the wallet modules
• transaction signing and verification functions

Typical uses:

• create or load encrypted wallets
• convert long addresses to short addresses
• validate short or vanity addresses
• sign transaction hashes
• verify signatures

Blocks and Transactions

Useful for tools that need to construct, decode or inspect transactions.

Common areas:

• blocks::block
• blocks::transfer
• blocks::token
• blocks::nft
• blocks::swap
• blocks::loans
• blocks::loan_payment
• blocks::collateral
• blocks::vanity

Typical uses:

• create transaction structs
• encode transactions into bytes
• decode transactions from bytes
• inspect transaction fields
• apply or undo balance-sheet effects

For user-facing transaction behavior, see TRANSACTIONS.md.

Common Hashing and Types

Useful for tools that need protocol constants or hashing compatible with the node.

Common areas:

• common::types
• common::skein
• common::network_paths_and_settings
• common::cli_prompts

Typical uses:

• access transaction type IDs
• access fee constants
• hash text or bytes with the same Skein helpers used by the node
• resolve network-scoped paths
• share CLI prompt behavior across tools

RPC

Useful for network clients, node tools and server command development.

Common areas:

• rpc::command_maps
• rpc::commands
• rpc::client
• rpc::server
• rpc::structs

Typical uses:

• map command IDs to RPC behavior
• implement a new RPC command handler
• inspect client request helpers
• inspect response structures

For raw client handshake notes, see DEV_CLIENTS.md.

Standalone Tool Connections

Useful for CLI tools that need to connect to a peer without acting like a mining node.

Common areas:

• standalone_tools::connections::handshake
• standalone_tools::connections::sending_request
• standalone_tools::connections::transaction_creator

Typical uses:

• perform the authenticated client handshake
• send a binary RPC request
• decode reply payloads for CLI output

Torrent and Orphan Handling

Useful for tools that inspect block synchronization behavior.

Common areas:

• torrent
• orphans
• records::staged_torrents

Typical uses:

• read and decode torrent metadata
• validate torrent data before block download
• inspect staged torrent candidates
• understand orphan correction and replay behavior

Records and Storage

Useful for tools that inspect local chain state or database-backed records.

Common areas:

• records::record_chain
• records::balance_sheet
• records::wallet_registry
• records::postgres
• records::memory
• records::network_mapping

Typical uses:

• read saved chain records
• inspect balance sheets
• resolve registered wallets or vanity addresses
• query or maintain PostgreSQL-backed lookup records
• inspect in-memory connection state

Adding New Public API

Before making a new function public, check whether it is public for one of these reasons:

• another module must call it
• a CLI tool needs it
• an external developer should reasonably use it
• Rustdoc should expose it as part of a stable integration surface

If a function only wraps one other function and adds no validation, conversion, ownership boundary or domain meaning, prefer calling the original function directly.

Adding New CLI Tools

Standalone CLI tools live in src/bin.

When adding a tool:

• use common::cli_prompts for user prompts
• use standalone_tools::connections for RPC client requests
• keep RPC payloads binary across the TCP stream
• print human-readable or JSON-decoded output only after the binary response is received
• add the tool to CLI_TOOLS.md

Adding New RPC Commands

RPC command handlers should live under src/rpc/commands.

When adding a command:

• add or update the command ID in rpc::command_maps
• put the command handler in rpc::commands
• keep inline code in the server loop minimal
• send and receive binary payloads across the stream
• return through RpcResponse directly
• add or update any matching CLI tool documentation

Documentation Map

• README.md: build, configure and start a node
• CLI_TOOLS.md: command-line tool reference
• TRANSACTIONS.md: transaction behavior reference
• POSTGRES.md: manual PostgreSQL setup
• SETTINGS.md: settings.ini field reference
• DEV_CLIENTS.md: low-level client handshake and request notes