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:

```bash
cargo build --release
```

Explicit testnet build:

```bash
cargo build --release --features testnet
```

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

```bash
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:

```bash
cargo doc --no-deps
```

Open the generated reference:

```text
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](src/branch/main/docs/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](src/branch/main/docs/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](src/branch/main/docs/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](src/branch/main/README.md): build, configure and start a node
- [CLI_TOOLS.md](src/branch/main/docs/CLI_TOOLS.md): command-line tool reference
- [TRANSACTIONS.md](src/branch/main/docs/TRANSACTIONS.md): transaction behavior reference
- [POSTGRES.md](src/branch/main/docs/POSTGRES.md): manual PostgreSQL setup
- [SETTINGS.md](src/branch/main/docs/SETTINGS.md): `settings.ini` field reference
- [DEV_CLIENTS.md](src/branch/main/docs/DEV_CLIENTS.md): low-level client handshake and request notes