contractless/Contractless
contractless
/
Contractless
1
1
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity

Update README.md

This commit is contained in:
contractless 2026-07-12 15:08:16 +00:00
parent 81f8f6e711
commit 4d559c710a
1 changed files with 55 additions and 292 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

347
README.md
View File

@ -1,319 +1,82 @@
# Contractless # Contractless
Contractless is a peer-to-peer Fair-Proof-of-Work blockchain with native multi-asset transactions, torrent-based block synchronization and deterministic orphan correction. This README contains the minimum information needed to build, configure and start a node. 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.
For the protocol design, mining rules, balance-sheet model and orphan correction process, read the [Contractless whitepaper](https://contractless.community/contractless_whitepaper.pdf). 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.
## Table of Contents 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.
- [System Requirements](#system-requirements) 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).
- [Network Requirements](#network-requirements)
- [Build Instructions](#build-instructions)
- [PostgreSQL Setup](#postgresql-setup)
- [Settings Configuration](#settings-configuration)
- [Runtime Paths](#runtime-paths)
- [Startup](#startup)
- [Additional Documentation](#additional-documentation)
## System Requirements: ## System Requirements
- Dedicated Internet Recommended node requirements:
- PC / Laptop / Hosted VPS or cloud hostingg
- Minimum 16GB memory 24 - 32 GB recommended
- i5 or higher CPU (or AMD equivalent CPU)
## Network 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
A public node needs to be reachable by other peers. Contractless uses Falcon signatures and requires 64-bit processing support.
- Open the active RPC port in the local firewall. ## Networking Requirements
- Forward the active RPC port through the router or host firewall when behind NAT.
- Set `IP` in `settings.ini` to the reachable public IP or reachable domain name for the node.
- Keep system time synchronized. Any reliable NTP/time server should work because Contractless only requires second-level timestamp agreement. A common default is `pool.ntp.org`.
- Keep PostgreSQL reachable locally by the node process.
Loopback and private addresses are useful for local testing, but they should not be announced by a public node. 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
## Build Instructions Loopback and private addresses are fine for local testing, but public testnet nodes must announce a reachable public IP.
Install Rust and build from the repository root. ## Download Source
Clone the repository:
```bash ```bash
cargo build --release git clone https://contractless.dev/contractless/Contractless.git
cd Contractless
``` ```
The default build target is testnet. ## Precompiled Binaries
### Build Flags Precompiled releases are available here:
Testnet is the default feature: [https://contractless.dev/contractless/Contractless/releases](https://contractless.dev/contractless/Contractless/releases)
```bash Use the release package that matches your operating system and follow the matching installation guide below.
cargo build --release
```
or explicitly: ## Documentation
```bash 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.
cargo build --release --features testnet
```
Mainnet has a feature flag, but mainnet builds are intentionally disabled during the testnet phase: | 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. |
```bash ## Current Status
cargo build --release --no-default-features --features mainnet
```
That command will fail until mainnet is enabled for launch. Contractless is still under active testnet development. Interfaces, transaction tools, docs, and node behavior may continue to change while the chain is tested.
## PostgreSQL Setup 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.
Contractless uses PostgreSQL for transaction lookup and mempool-style records. PostgreSQL only needs a database, user, password and permissions before the node starts. On startup, the node creates or migrates the required tables and indexes automatically. The node also uses local file and sled storage for chain state, wallets, balance sheets and torrents.
### Linux PostgreSQL CLI Tool
Build the release binaries, then run the installer as root so it can install PostgreSQL if needed and create the database, user, password and permissions:
```bash
sudo ./target/release/postgres_installer
```
After the tool completes, copy the printed PostgreSQL values into the active PostgreSQL section of `settings.ini`.
### Windows PostgreSQL CLI Tool
Open PowerShell as Administrator, copy the built installer into the install folder, then run it:
```powershell
& "C:\Program Files\Contractless\postgres_installer.exe"
```
The Windows installer downloads and installs PostgreSQL when needed, then creates the configured database, user, password and permissions.
### Manual PostgreSQL Setup
Manual PostgreSQL instructions should live in [docs/POSTGRES.md](src/branch/main/docs/POSTGRES.md). Until that file is fully written, use the CLI installer unless you already know how to create the database, user and permissions manually.
## Settings Configuration
The node loads `settings.ini` in this order:
1. `--config <path>`
2. `SETTINGS_PATH` environment variable
3. `./settings.ini`
4. `settings.ini` beside the executable
5. platform fallback path
On Linux, the fallback path is:
```text
/etc/contractless/settings.ini
```
On Windows, place `settings.ini` beside the executable:
```text
C:\Program Files\Contractless\settings.ini
```
### Basic `settings.ini` Shape
```ini
[Paths]
BLOCK_PATH = "./blocks"
TORRENT_PATH = "./torrents"
DB_PATH = "./state"
BALANCE_SHEET = "./balance_sheet"
LOG_PATH = "./logs"
WALLET_PATH = "./wallets"
WALLET_NAME = "contractless.wallet"
[Settings]
LOG_LEVEL = "info"
IP = "YOUR.PUBLIC.IP.ADDRESS"
LISTEN_IP = "0.0.0.0"
RPC_PORT = "50050"
TESTNET_RPC_PORT = "50055"
INCOMING_CONNECTIONS = "100"
OUTGOING_CONNECTIONS = "10"
VALIDATOR = "false"
THREADS = "8"
[Piggyback]
PIGGYBACK_1 = "contractless.dev:50050"
[Postgres-Testnet]
host = 127.0.0.1
port = 5432
user = contractless
password = your_postgres_password_here
dbname = contractless_db
[Postgres]
host = 127.0.0.1
port = 5432
user = contractless
password = your_postgres_password_here
dbname = contractless_db
```
`THREADS` must be `1`, `2` or a multiple of `4`, and may not be greater than `256`.
`LOG_LEVEL` follows normal logging filters:
- `info` shows info, warning and error logs.
- `warn` shows warning and error logs.
- `error` shows only error logs.
- `off` disables log output.
Detailed settings notes should live in [docs/SETTINGS.md](src/branch/main/docs/SETTINGS.md).
## Runtime Paths
Relative paths in `settings.ini` are resolved relative to the location of that `settings.ini` file. The node scopes runtime data by active network internally, so testnet and mainnet paths do not collide when using the same base folders.
The main runtime folders are:
- `BLOCK_PATH`: saved block files
- `TORRENT_PATH`: torrent metadata and staged torrents
- `DB_PATH`: sled state
- `WALLET_PATH`: encrypted wallet files
- `BALANCE_SHEET`: balance sheet files
- `LOG_PATH`: runtime logs
### Linux Copy Instructions
Create the config folder and copy the sample settings file:
```bash
sudo mkdir -p /etc/contractless
sudo cp ./settings.ini /etc/contractless/settings.ini
```
Copy the node binary:
```bash
sudo cp ./target/release/contractless-testnet /usr/bin/
```
Copy any CLI tools you want available system-wide:
```bash
sudo cp ./target/release/postgres_installer /usr/bin/
sudo cp ./target/release/create_new_wallet /usr/bin/
sudo cp ./target/release/register_wallet /usr/bin/
```
Repeat the same pattern for any other tools from `target/release`.
### Windows Copy Instructions
Open PowerShell as Administrator and create the install folder:
```powershell
New-Item -ItemType Directory -Force "C:\Program Files\Contractless" | Out-Null
```
Copy the node, key-submit tool, PostgreSQL installer and settings file:
```powershell
Copy-Item ".\target\release\contractless-testnet.exe" "C:\Program Files\Contractless\"
Copy-Item ".\target\release\contractless-submit-key.exe" "C:\Program Files\Contractless\"
Copy-Item ".\target\release\postgres_installer.exe" "C:\Program Files\Contractless\"
Copy-Item ".\settings-windows.ini" "C:\Program Files\Contractless\settings.ini"
```
Copy any additional CLI tools the same way.
## Startup
Create or restore a wallet before starting a public node, then make sure the wallet is registered and the wallet path/name in `settings.ini` matches the runtime wallet.
### Linux Startup
Start the testnet node:
```bash
contractless-testnet
```
Linux prompts for the wallet decryption key, then detaches into the background automatically.
Run in the foreground for debugging:
```bash
contractless-testnet --foreground
```
Check daemon status:
```bash
contractless-testnet --status
```
Stop the daemon:
```bash
contractless-testnet --stop
```
Use a specific config file:
```bash
contractless-testnet --config /path/to/settings.ini
```
### Windows Startup
Open PowerShell as Administrator and install the service:
```powershell
& "C:\Program Files\Contractless\contractless-testnet.exe" --install-service
```
Start the service:
```powershell
& "C:\Program Files\Contractless\contractless-testnet.exe" --start-service
```
Submit the wallet decryption key from a normal user shell:
```powershell
& "C:\Program Files\Contractless\contractless-submit-key.exe"
```
Stop the service:
```powershell
& "C:\Program Files\Contractless\contractless-testnet.exe" --stop-service
```
Uninstall the service:
```powershell
& "C:\Program Files\Contractless\contractless-testnet.exe" --uninstall-service
```
### Startup Flags
Node flags:
- `--config <path>`: load a specific `settings.ini`.
- `--foreground`: Linux only; keep the process attached to the terminal.
- `--status`: Linux only; check daemon status.
- `--stop`: Linux only; stop the daemon.
- `--install-service`: Windows only; install the Windows service.
- `--start-service`: Windows only; start the Windows service.
- `--stop-service`: Windows only; stop the Windows service.
- `--uninstall-service`: Windows only; uninstall the Windows service.
## Additional Documentation
- [Whitepaper](https://contractless.community/contractless_whitepaper.pdf)
- [Manual PostgreSQL setup](src/branch/main/docs/POSTGRES.md)
- [Settings reference](src/branch/main/docs/SETTINGS.md)
- [CLI tools reference](src/branch/main/docs/CLI_TOOLS.md)
- [Transaction reference](src/branch/main/docs/TRANSACTIONS.md)
- [Developer guide](src/branch/main/docs/DEV.md)