bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 18쪽 중 3쪽
# HTTP RPC
- "18200:18200" # WebSocket
- "19000:19000" # P2P TCP
- "20000:20000" # RPC
restart: unless-stopped
ulimits:
nofile:
soft: 10000000
hard: 10000000
healthcheck:
test: ["CMD", "curl", "-sf", "-X", "POST", "-H", "Content-Type: application/json", "-d", "{\"jsonrpc\":\"2.0\",\"method\":\"eth_blockNumber\",\"params\":[],\"id\":1}", "http://localhost:18100"]
interval: 30s
timeout: 10s
retries: 3
start_period: 60s
EOF
```
**Note:** The image uses a specific version tag (`pharos_community_v0.16.0_3cf35988_0914`).
## **4. Set password in docker-compose.yml**
Edit `docker-compose.yml` and set your password:
```bash
vim docker-compose.yml
```
Change this line:
```yaml
- CONSENSUS_KEY_PWD=YOUR_PASSWORD_HERE
```
To your actual password:
```yaml
- CONSENSUS_KEY_PWD=your_secure_password
```
## **5. Verify required files**
Before starting the container, verify all required files are present:
```bash
tree .
```
You should see:
```
.
├── bin
│ └── VERSION
├── docker-compose.yml
├── genesis.conf
└── pharos.conf
```
**Required files:**
* `genesis.conf` - Genesis configuration
* `pharos.conf` - Node configuration
* `docker-compose.yml` - Docker Compose configuration with your password
* `bin/VERSION` - Network version information
**Missing files?** Go back to steps 2-4 to download and configure them.
## **6. Start the node**
Start the Pharos node with Docker Compose:
```bash
docker compose up -d
```
## **7. Check node status**
View logs:
```bash
docker compose logs -f pharos
```
Check if the node is running:
```bash
docker compose ps
```
You should see:
```
NAME IMAGE STATUS PORTS
pharos-node public.ecr.aws/k2g7b7g1/pharos:pharos_community_v0.16.0_3cf35988_0914 Up 2 minutes 0.0.0.0:18100->18100/tcp, ...
```
Check node health:
```bash
curl http://localhost:18100
```
## **Managing the node**
### Stop the node
```bash
docker compose stop
```
### Restart the node
```bash
docker compose restart
```
### Stop and remove the container
```bash
docker compose down
```
**Note:** This does not delete your data. Data is persisted in `/data/pharos/`.
### View real-time logs
```bash
docker compose logs -f
```
### Execute commands in the container
```bash
docker compose exec pharos bash
```
## **Directory Structure**
After deployment, your directory structure will look like:
```
/data/pharos/
├── bin/ # Auto-copied from image on each start
│ ├── pharos_light
│ ├── pharos_cli
│ └── VERSION
├── ops # Auto-copied from image on each start
├── keys/ # Auto-generated on first start
│ ├── domain.key
│ ├── domain.pub
│ ├── stabilizing.key
│ └── stabilizing.pub
├── data/ # Created after bootstrap
│ └── meta_store/
├── log/
│ ├── aldaba.log
│ ├── aldaba_cli.log
│ └── pamir.log
├── genesis.conf # Downloaded in step 2
├── pharos.conf # Downloaded in step 2
└── docker-compose.yml # Created in step 3, edited in step 4
```
## **Upgrading the node**
To upgrade to a new version, update the image tag in `docker-compose.yml` to the new version, then:
```bash
# Pull the new image
docker compose pull
# Restart with new image
docker compose up -d
```
## **Security Recommendations**
1. **Use strong passwords**: Set a secure password for `CONSENSUS_KEY_PWD`
2. **Protect your keys**: Ensure `/data/pharos/keys/` has proper permissions
3. **Firewall configuration**: Only expose necessary ports
4. **Regular backups**: Backup `/data/pharos/keys/` and `pharos.conf`
5. **Keep updated**: Regularly pull and update to the latest image
6. **Monitor logs**: Regularly check logs for errors or warnings
## **Next Steps**
* [Node Monitoring Setup](/node-and-validator-guide/node-monitoring-setup) - Configure Prometheus metrics for your node
# Using Binary
This guide describes how to deploy a Pharos node using pre-compiled binaries and the ops tool.
> 📌 For the latest binary package, see [Current Node Versions](/node-and-validator-guide/validator-node-deployment#current-node-versions).
## **Prerequisites**
| Component | Specification |
| ----------------- | ----------------------------------------------------------------- |
| CPU | 32 cores, 2.8GHz or faster, AMD Milan EPYC or Intel Xeon Platinum |
| Memory | 256 GB |
| Storage | 5 TB SSD with at least 350MiB/s bandwidth and 30000 IOPS |
| Network Bandwidth | 0.5 Gbps |
| Open Files Limit | ulimit -n ≥ 10000000 |
## **1. Create working directory and download binary package**
```bash
export WORKSPACE=pharos
mkdir -p /data/$WORKSPACE && cd /data/$WORKSPACE
```
Download the latest binary release from GitHub:
```bash
wget https://github.com/PharosNetwork/resources/releases/download/v0.16.0/pharos-v0.16.0-3cf35988.tar.gz
tar -zxvf pharos-v0.16.0-3cf35988.tar.gz
```
The extracted package contains:
* `bin/pharos_light` - Pharos node binary
* `bin/pharos_cli` - Pharos CLI tool
## **2. Download configuration files**
Download the genesis configuration and VERSION file based on your network:
**For Atlantic Testnet:**
```bash
wget -O genesis.conf https://raw.githubusercontent.com/PharosNetwork/resources/refs/heads/main/atlantic.genesis
wget -O bin/VERSION https://raw.githubusercontent.com/PharosNetwork/resources/refs/heads/main/atlantic.version
```
**For Mainnet:**
```bash
wget -O genesis.conf https://raw.githubusercontent.com/PharosNetwork/resources/refs/heads/main/mainnet.genesis
wget -O bin/VERSION https://raw.githubusercontent.com/PharosNetwork/resources/refs/heads/main/mainnet.version
```
> **Note:** When upgrading to a new version, you must also re-download the VERSION file to keep it in sync.
Download the node configuration file (choose one based on your node type):
**For Archive/Full/Validator Node:**
```bash
wget -O pharos.conf https://raw.githubusercontent.com/PharosNetwork/resources/refs/heads/main/conf/full.conf
```
> **Note:** Pruning is disabled by default. To enable pruning, see [Enable Pruning in Pharos Node](/enable-pruning-in-pharos-node).
**For TraceDB Node:**
```bash
wget -O pharos.conf https://raw.githubusercontent.com/PharosNetwork/resources/refs/heads/main/conf/traceDB.conf
```
## **3. Download and setup ops tool**
Download the latest ops tool for Linux:
```bash
wget https://github.com/PharosNetwork/ops/releases/latest/download/ops-linux-amd64 -O ops
chmod +x ops
```
## **4. Set password for key encryption**
Set a password that will be used to encrypt your node's cryptographic keys:
```bash
./ops set-password YOUR_SECURE_PASSWORD
```
**Important:**
* Remember this password - you'll need it to start your node
* The password is stored in `./.password` file
* Keep this password secure and backed up
## **5. Generate cryptographic keys**
Generate the domain and stabilizing keys for your node:
```bash
./ops generate-keys
```
This will create the following files in the `./keys/` directory:
* `domain.key` - ECDSA private key (prime256v1)
* `domain.pub` - ECDSA public key
* `stabilizing.key` - BLS12-381 private key
* `stabilizing.pub` - BLS12-381 public key
## **6. Bootstrap the node**
Initialize the node with genesis state:
```bash
./ops bootstrap --config ./pharos.conf
```
This command will:
* Create the storage database
* Initialize the genesis block
* Prepare the node for first startup
## **7. Start the node**
Start the Pharos node service:
```bash
./ops start --config ./pharos.conf
```
The node will start in daemon mode and begin syncing with the network.
Check the logs to verify the node is running:
```bash
tail -f log/aldaba.log
```
## **8. (Optional) Setup systemd service**
For production deployments, it's recommended to manage the Pharos node with systemd.
Create a systemd service file:
```bash
sudo tee /etc/systemd/system/pharos.service > /dev/null <<EOF
[Unit]
Description=Pharos Node
After=network.target
[Service]
Type=simple
User=$USER
WorkingDirectory=/data/$WORKSPACE/bin
Environment="CONSENSUS_KEY_PWD=$(cat /data/$WORKSPACE/.password)"
Environment="PORTAL_SSL_PWD=$(cat /data/$WORKSPACE/.password)"
ExecStart=/data/$WORKSPACE/bin/pharos_light -c /data/$WORKSPACE/pharos.conf
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
# Resource limits
LimitNOFILE=10000000
[Install]
WantedBy=multi-user.target
EOF
```
Enable and start the service:
```bash
sudo systemctl daemon-reload
sudo systemctl enable pharos
sudo systemctl start pharos
```
Check service status:
```bash
sudo systemctl status pharos
```
View logs:
```bash
sudo journalctl -u pharos -f
```
**Note:** If not using systemd, you can manually stop the node with `pkill pharos_light` and restart with `./ops start --config ./pharos.conf`
## **Directory Structure**
After deployment, your directory structure should look like:
```
/data/pharos/
├── bin/
│ ├── pharos_light
│ ├── pharos_cli
│ └── VERSION
├── keys/
│ ├── domain.key
│ ├── domain.pub
│ ├── stabilizing.key
│ └── stabilizing.pub
├── data/
│ └── (blockchain data)
├── log/
│ ├── aldaba.log
│ ├── pamir.log
│ └── (other logs)
├── genesis.conf
├── pharos.conf
├── ops
└── .password
```
## **9. (Optional) Register as Validator**
If you want to run a validator node, you need to register your node on-chain after it has synced with the network.
### Set up your validator private key
The validator registration requires an Ethereum-compatible private key that holds sufficient tokens for staking. Set it as an environment variable:
```bash
export VALIDATOR_PRIVATE_KEY=your_private_key_hex
```
> **Security Note:** Do not pass the private key via command-line arguments. Always use the environment variable.
### Register the validator
```bash
./ops add-validator \
--rpc-endpoint http://127.0.0.1:18100 \
--domain-label "My Validator Node" \
--domain-endpoint "your-node-public-endpoint:20000" \
--domain-pubkey ./keys/domain.pub \
--stabilizing-pubkey ./keys/stabilizing.pub \
--stake 1000000
```
Parameters:
* `--rpc-endpoint` - RPC endpoint of a synced Pharos node (default: `http://127.0.0.1:18100`)
* `--domain-label` - A description for your validator
* `--domain-endpoint` - The public-facing endpoint of your node for P2P communication
* `--domain-pubkey` - Path to the domain public key file generated in Step 5
* `--stabilizing-pubkey` - Path to the stabilizing public key file generated in Step 5
* `--stake` - Stake amount in tokens (default: 1,000,000 tokens)
On success, the command will output the transaction hash and your Node ID.
### Exit the validator (if needed)
To voluntarily exit your validator from the network:
```bash
export VALIDATOR_PRIVATE_KEY=your_private_key_hex
./ops exit-validator \
--rpc-endpoint http://127.0.0.1:18100 \
--domain-pubkey ./keys/domain.pub
```
## **Security Recommendations**
1. **Protect your keys**: The files in `keys/` directory contain your node's private keys
2. **Secure your password**: Keep the `.password` file secure with proper permissions
3. **Backup important files**: Backup `keys/`, `.password`, and `pharos.conf`
4. **Firewall configuration**: Ensure required ports are open (18100, 19000, 20000)
5. **Regular updates**: Keep your node software up to date with latest releases
## **Next Steps**
* [Node Monitoring Setup](/node-and-validator-guide/node-monitoring-setup) - Configure Prometheus metrics for your node
* To register as a validator, see Step 9 above
# Node Configuration
This document provides detailed configuration guidance for Pharos nodes, including node types, configuration files, RPC tuning, and node pool scheduling strategies.
## Node Types
Pharos supports the following node types:
| Node Type | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Validator Node** | Joins the consensus network and participates in block production through consensus. |
| **Fullnode** | Similar to validator node, but not included in the consensus node set. Serves as a regular RPC node or as a failover backup for validators. |
| **Full Cache Node** | A fullnode with an additional flat state database to accelerate state data queries. |
| **Tracedb Node** | A fullnode with an additional trace database to accelerate trace-related request responses. |
***
## Node Configuration (pharos.conf)
### Base Configuration
All node types share the same base configuration. Pre-built configuration files are available:
* **Fullnode / Validator**: [full.conf](https://raw.githubusercontent.com/PharosNetwork/resources/main/conf/full.conf)
* **Full Cache Node**: [full-cache-node.conf](https://raw.githubusercontent.com/PharosNetwork/resources/main/conf/full-cache-node.conf)
* **Tracedb Node**: [traceDB.conf](https://raw.githubusercontent.com/PharosNetwork/resources/main/conf/traceDB.conf)
The base configuration for fullnode/validator:
```json
{
"chain": {
"secret_config": {
"domain_key_path": "../keys/domain.key",
"stabilizing_key_path": "../keys/stabilizing.key"
},
"startup_config": {
"init_config": {
"meta_path": "../data",
"host_ip": "127.0.0.1",
"http_port": "18100",
"rpc_port": "20000",
"tcp_port": "19000",
"ws_port": "18200"
}
}
},
"storage": {
"mygrid_conf": {},
"mygrid_env": {
"storage_data_path": "../data"
}
}
}
```
### Enabling Full Cache Node (Flat State KV DB)
To accelerate state data queries (e.g., `getBalance`, `getCode`, `getStorageAt`), enable the flat state KV database on top of the base configuration:
```json
{
"storage": {
"mygrid_conf": {
"config": {
"mygrid": {
"expert_flags": {
"mygrid_client_enable_full_state_kv_db": true
}
}
}
}
}
}
```
This adds a secondary key-value index alongside the Merkle state database, providing O(1) lookups for account and storage data across all historical blocks. Recommended for RPC nodes serving high-volume state queries.
### Enabling Tracedb Node
To support `debug_traceTransaction`, `debug_traceBlockByHash`, `debug_traceBlockByNumber`, and `trace_filter`, enable trace persistence on top of the base configuration:
```json
{
"chain": {
"startup_config": {
"parameters": {
"/GlobalFlag/enable_persist_trace": "true"
}
}
}
}
```
This persists transaction execution traces to a dedicated database, enabling trace replay without re-executing transactions. Recommended for nodes serving debug/trace API requests.
### Combining Full Cache + Tracedb
Both features can be enabled simultaneously for maximum query capability:
```json
{
"chain": {
"startup_config": {
"parameters": {
"/GlobalFlag/enable_persist_trace": "true"
}
}
},
"storage": {
"mygrid_conf": {
"config": {
"mygrid": {
"expert_flags": {
"mygrid_client_enable_full_state_kv_db": true
}
}
}
}
}
}
```
> **Note:** Enabling both features increases disk usage significantly. Plan for additional storage capacity beyond the base 5 TB requirement.
***
## RPC Node Tuning
Since RPC nodes primarily handle state queries, block queries, and simulated transaction execution, they require strong JSON-RPC layer processing capabilities. The following configurations can be used to tune the JSON-RPC layer processing logic.
### Thread Counts and Queue Sizes
| Configuration Item | Default Value | Purpose | Impact on RPC Node Performance |
| ------------------------------- | ------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `cache_query_worker_count` | 16 | Handles `getBlock*`/`getTx*`/`getReceipt*` and other cache queries | **High**: Insufficient workers cause queuing and increased latency |
| `cache_query_worker_queue_size` | 1000 | Pending queue for above workers | Queue full at high QPS will reject or block |
| `db_query_worker_count` | 4 | Handles `getBalance`/`getCode`/`getStorageAt` and other state queries | **High**: Easy to become bottleneck when state queries are frequent |
| `db_query_worker_queue_size` | 1000 | Queue for above | Can increase appropriately |
| `heavy_task_worker_count` | 4 | Handles `getLogs`, `feeHistory` | **Medium**: `getLogs` is time-consuming, need more workers when concurrent |
| `heavy_task_worker_queue_size` | 1000 | Queue for above | Can increase when heavy tasks are frequent |
| `eth_default_worker_count` | 4 | `blockNumber`, `syncing`, `chainId`, `gasPrice`, `subscribe`, etc. | **Medium**: Can slightly increase when connection count is high |
| `sim_tx_worker_count` | 16 | `eth_call`, `estimateGas`, `createAccessList` | **Medium-High**: Easy to become bottleneck when dApps have many `eth_call` requests |
| `raw_tx_worker_count` | 10 | `sendRawTransaction` | **Low**: Can reduce if node doesn't primarily receive transactions |
### Session Management
| Configuration Item | Default Value | Purpose | Impact |
| ------------------------------- | ------------- | ----------------------------------- | ---------------------------------------------------------------- |
| `max_session` | 102400 | Maximum session count | Needs to be large enough for multi-client scenarios |
| `max_batch_request_size` | 20 | Single batch JSON-RPC request count | Increasing can reduce connections and round-trips |
| `enable_http_long_connection` | true | HTTP long connection | Recommend keeping `true` to reduce connection overhead |
| `session_idle_timeout_for_http` | 400000 | HTTP session idle timeout (ms) | Reduces invalid connections |
| `session_idle_timeout_for_ws` | 360000 | WebSocket session idle timeout (ms) | Reduces invalid connections |
| `socket_thread_count` | 16 | Accept connections, read socket | Insufficient when connection count is high will limit throughput |
### Block Cache
| Configuration Item | Default Value | Purpose | Impact |
| ------------------ | ------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `cache_depth` | 2048 | Number of recent blocks cached (header/body/tx/receipt) | `getBlock*`/`getTx*`/`getReceipt*` cache hit avoids disk read, increasing can significantly improve hit rate and reduce latency |
***
## Node Pool JSON-RPC API Scheduling Strategy
Recommendations for node pool `eth` JSON-RPC API scheduling:
### By Node Type
| Node Type | Scheduling Rule |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tracedb Node** | `trace_filter` can **only** be served by tracedb node. `debug_traceBlockByHash`, `debug_traceBlockByNumber`, `debug_traceTransaction` should be **preferentially** scheduled to tracedb node. |
| **RPC Node** | Interfaces other than trace/debug can be scheduled to regular RPC nodes. |
| **Fullnode** | Can be scheduled as a regular RPC node. |
| **Validator Node** | **Do not** schedule any JSON-RPC requests, only handle transactions forwarded from other RPC nodes. |
### By Data Availability
When fullnode enables state data pruning and only retains `(latest - pruning_window, latest]`, please note the state data availability range and request range in scheduling strategy.
### By Interface Affinity
Affinity-related requests need to be scheduled to the **same node**:
* **Transaction submission group**: `eth_sendRawTransaction` and related queries `eth_getTransactionCount`, `eth_getTransactionByHash`, `eth_estimateGas`/`eth_call`, especially pending state-based queries.
* **Filter group**: `eth_newFilter`, `eth_newBlockFilter`, `eth_newPendingTransactionFilter` for monitoring and event retrieval `eth_getFilterChanges`. (Pharos currently uses `eth_subscribe` instead of filter interfaces.)
# Node Management
### Node Initialization
Pharos Full Nodes automatically generate cryptographic keys on startup — no manual configuration is needed. To start a validator node, run the following command in your working directory:
```sh
docker start atlantic-testnet
프로젝트로 돌아가기