Contractless/README.md

# Contractless

Contractless is a new peer-to-peer blockchain built from the ground up around spendable digital money, native transaction types, and a consensus model called Fair Proof of Work.

Instead of rewarding specialized mining hardware with overwhelming advantage, Contractless limits mining attempts so ordinary hardware can participate on more equal footing. The chain includes native support for base-currency transfers, tokens, NFTs, swaps, loans, marketing records, and app-style data storage without requiring a smart-contract VM.

Contractless is currently in testnet. Node operators, developers, wallet testers, and application builders are encouraged to review the documentation, run testnet nodes, and help test the network.

For protocol design, mining rules, balance handling, orphan correction, and Fair Proof of Work details, read the [Contractless whitepaper](https://contractless.community/contractless_whitepaper.pdf).

## System Requirements

Recommended node requirements:

- 64-bit Windows or Linux
- Dedicated internet connection
- Publicly reachable PC, laptop, VPS, cloud server, or self-hosted server
- 16 GB RAM minimum
- 24 GB to 32 GB RAM recommended
- Intel i5 or better, or comparable AMD CPU
- PostgreSQL installed locally or reachable by the node
- Enough disk space for blocks, torrents, balance data, logs, and state files

Contractless uses Falcon signatures and requires 64-bit processing support.

## Networking Requirements

A public Contractless node must be reachable by other peers.

- Public IP address
- Open RPC port
- Router or host firewall port forwarding when behind NAT
- `PUBLIC_IP` in `settings.ini` set to the reachable public IP
- `LISTEN_IP` usually set to `0.0.0.0`
- Correct `RPC_PORT` and `TESTNET_RPC_PORT`
- Reliable system time using NTP or another time synchronization service
- One mining node per public IP

Loopback and private addresses are fine for local testing, but public testnet nodes must announce a reachable public IP.

## Download Source

Clone the repository:

```bash
git clone https://contractless.dev/contractless/Contractless.git
cd Contractless
```

## Precompiled Binaries

Precompiled releases are available here:

[https://contractless.dev/contractless/Contractless/releases](https://contractless.dev/contractless/Contractless/releases)

Use the release package that matches your operating system and follow the matching installation guide below.

## Documentation

The documentation is being reorganized into focused guides. Each guide explains the concept, required setup, common workflows, and relevant CLI tools instead of only listing commands.

| Guide | Description |
| --- | --- |
| [Linux Installation](src/branch/main/docs/LINUX_INSTALLATION.md) | Install, configure, and run a Contractless node on Linux. |
| [Windows Installation](src/branch/main/docs/WINDOWS_INSTALLATION.md) | Install, configure, and run a Contractless node on Windows. |
| [Manual Postgres Setup](src/branch/main/docs/POSTGRES.md) | Manually create the PostgreSQL database, user, permissions, and settings. |
| [Config Settings](src/branch/main/docs/SETTINGS.md) | Full `settings.ini` reference and runtime path behavior. |
| [Wallet Tools](src/branch/main/docs/WALLET_TOOLS.md) | Create, restore, register, validate, and manage wallets. |
| [Validation Tools](src/branch/main/docs/VALIDATION_TOOLS.md) | Validate addresses, messages, blocks, torrents, and chain data. |
| [NFT Transactions](src/branch/main/docs/NFT_TRANSACTIONS.md) | Create, transfer, burn, and understand NFTs and RWA metadata. |
| [Token Swaps](src/branch/main/docs/TOKEN_SWAPS.md) | Create, sign, import, and broadcast two-party swap transactions. |
| [Loan Transactions](src/branch/main/docs/LOAN_TRANSACTIONS.md) | Create loans, make payments, claim collateral, and understand loan rules. |
| [Data Storage](src/branch/main/docs/DATA_STORAGE.md) | Create storage keys, write app data, and use paid storage lookups. |
| [Marketing Transactions](src/branch/main/docs/MARKETING_TRANSACTIONS.md) | Record campaign data and query marketing activity. |
| [Other Tools and Transactions](src/branch/main/docs/OTHER_TOOLS_AND_TRANSACTIONS.md) | Additional CLI tools, transaction types, and maintenance commands. |
| [Developers](src/branch/main/docs/DEV.md) | Architecture notes, library structure, RPC behavior, and contribution guidance. |

## Current Status

Contractless is still under active testnet development. Interfaces, transaction tools, docs, and node behavior may continue to change while the chain is tested.

If you are interested in running a testnet node, start with the installation guide for your operating system, then review the configuration and wallet tools documentation.