Skip to content

Commit e84998e

Browse files
CryptoExplorCryptoExplor
authored
Update README.md
1 parent 6bd76ea commit e84998e

File tree

1 file changed

+22
-51
lines changed

1 file changed

+22
-51
lines changed

‎README.md‎

Lines changed: 22 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
1+
12
# ⚡ Celo Wallet Simulator
23

3-
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Node.js](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org/) [![CI](https://github.com/CryptoExplor/Celo-Wallet-Simulator/actions/workflows/node.yml/badge.svg)](https://github.com/CryptoExplor/Celo-Wallet-Simulator/actions) [![GitHub stars](https://img.shields.io/github/stars/CryptoExplor/Celo-Wallet-Simulator?style=social)](https://github.com/CryptoExplor/Celo-Wallet-Simulator/stargazers)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Node.js](https://img.shields.io/badge/node-%3E%3D18-green)](https://nodejs.org/) [![CI](https://github.com/CryptoExplor/Celo-Wallet-Simulator/actions/workflows/node.yml/badge.svg)](https://github.com/CryptoExplor/Celo-Wallet-Simulator/actions) [![GitHub stars](https://img.shields.io/github/stars/CryptoExplor/Celo-Wallet-Simulator?style=social)](https://github.com/CryptoExplor/Celo-Wallet-Simulator/stargazers)
45

56
A lightweight **wallet activity simulator** for the **Celo blockchain**, designed for:
67

@@ -13,21 +14,21 @@ A lightweight **wallet activity simulator** for the **Celo blockchain**, designe
1314

1415
## 📦 Features
1516

16-
* ✅ **In-memory encrypted private keys** (AES-256-GCM) — private keys are kept encrypted in memory and decrypted only when required for signing.
17-
* ✅ **Multi-master key support & rotation** — `MASTER_KEY` with optional `BACKUP_KEYS` for recovery and key rotation.
18-
* ✅ **Persona-driven wallet behavior** (`personas.json`) — idleBias, pingBias, activeHours, avgWait, retryBias, maxNonce, and device-agent.
19-
* ✅ **Device-agent support** — per-wallet `User-Agent` and simulated latency to diversify fingerprints.
20-
* ✅ **Configurable wait logic** — adaptive/random spacing to mimic organic activity.
21-
* ✅ **Multi-RPC rotation & proxy support** — automatic failover across Celo RPC endpoints; supports HTTP(S) and SOCKS proxies (`proxy.txt`).
22-
* ✅ **Adaptive activity patterns** — dynamic idleBias based on recent success/failure history.
23-
* ✅ **Structured CSV logging** — daily rotated `tx_log_YYYY-MM-DD.csv` with buffered flushes.
24-
* ✅ **Graceful shutdown** — signal handlers flush logs and persist personas.
17+
* ✅ **In-memory encrypted private keys** (AES-256-GCM): Private keys are kept encrypted in memory and decrypted only when required for signing.
18+
* ✅ **Multi-master key support & rotation**: `MASTER_KEY` with optional `BACKUP_KEYS` for recovery and key rotation.
19+
* ✅ **Persona-driven wallet behavior** (`personas.json`): Configurable parameters include `idleBias`, `pingBias`, `activeHours`, `avgWait`, `retryBias`, `maxNonce`, and `device-agent`.
20+
* ✅ **Device-agent support**: Per-wallet `User-Agent` and simulated latency to diversify fingerprints.
21+
* ✅ **Configurable wait logic**: Adaptive/random spacing to mimic organic activity.
22+
* ✅ **Multi-RPC rotation & proxy support**: Automatic failover across Celo RPC endpoints; supports HTTP(S) and SOCKS proxies (`proxy.txt`).
23+
* ✅ **Adaptive activity patterns**: Dynamic `idleBias` based on recent success/failure history.
24+
* ✅ **Structured CSV logging**: Daily rotated `tx_log_YYYY-MM-DD.csv` with buffered flushes.
25+
* ✅ **Graceful shutdown**: Signal handlers flush logs and persist personas.
2526

2627
---
2728

2829
## 🚀 Quick Start
2930

30-
1. **Clone the repo**
31+
1. **Clone the repository**
3132

3233
```bash
3334
git clone https://github.com/CryptoExplor/Celo-Wallet-Simulator.git
@@ -59,57 +60,27 @@ A lightweight **wallet activity simulator** for the **Celo blockchain**, designe
5960

6061
5. **Stop gracefully**
6162

62-
* Press `Ctrl+C` — the process will flush logs and save persona state before exit.
63-
64-
---
65-
66-
## 📘 Documentation
67-
68-
* 📄 [Usage Guide](./USAGE.md) – setup, personas, logging, workflow
69-
* 📄 [Architecture](./ARCHITECTURE.md) – system design & internals
63+
Press `Ctrl+C` — the process will flush logs and save persona state before exit.
7064

7165
---
7266

7367
## 🧩 Configuration & Files
7468

75-
* `index.js` — main runtime engine (encryption, personas, RPC/proxy logic, tx loop).
76-
* `personas.json` — persona defaults (created automatically if missing). The simulator also supports encrypted persona storage.
77-
* `inactive.json` — stores addresses marked outside their active hours (can be encrypted on disk if enabled).
78-
* `proxy.txt` — optional: one proxy URL per line (`http(s)://host:port` or `socks5://host:port`).
79-
* `key.txt` — legacy: one private key per line (not required if using `PRIVATE_KEYS` env).
80-
* `tx_log_YYYY-MM-DD.csv` — daily CSV logs with header: `timestamp,wallet,tx_hash,nonce,gas_used,gas_price_gwei,fee_celo,status,action`.
81-
82-
### Persona format (example)
83-
84-
Personas are stored as an object keyed by wallet address. Example:
85-
86-
```json
87-
{
88-
"0xabc...": {
89-
"idleBias": 0.12,
90-
"pingBias": 0.06,
91-
"minAmount": 0.0001,
92-
"maxAmount": 0.01,
93-
"activeHours": [2, 22],
94-
"cooldownAfterFail": 90,
95-
"avgWait": 45,
96-
"retryBias": 0.2,
97-
"maxNonce": 560,
98-
"failCount": 0,
99-
"lastFailAt": null,
100-
"deviceAgent": { "userAgent": "Chrome/102.0 (Windows NT 10.0)", "latency": 120 }
101-
}
102-
}
103-
```
69+
* `index.js`: Main runtime engine (encryption, personas, RPC/proxy logic, tx loop).
70+
* `personas.json`: Persona defaults (created automatically if missing). The simulator also supports encrypted persona storage.
71+
* `inactive.json`: Stores addresses marked outside their active hours (can be encrypted on disk if enabled).
72+
* `proxy.txt`: Optional: One proxy URL per line (`http(s)://host:port` or `socks5://host:port`).
73+
* `key.txt`: Legacy: One private key per line (not required if using `PRIVATE_KEYS` env).
74+
* `tx_log_YYYY-MM-DD.csv`: Daily CSV logs with header: `timestamp,wallet,tx_hash,nonce,gas_used,gas_price_gwei,fee_celo,status,action`.
10475

10576
---
10677

10778
## 🔒 Security Notes
10879

109-
* **MASTER\_KEY** encrypts private keys in memory and is required at process start. Provide it via OS-level secrets or a secure vault in production.
110-
* **BACKUP\_KEYS** allow decrypting older encrypted blobs after key rotation. The script attempts decryption with all provided master keys.
80+
* **MASTER_KEY** encrypts private keys in memory and is required at process start. Provide it via OS-level secrets or a secure vault in production.
81+
* **BACKUP_KEYS** allow decrypting older encrypted blobs after key rotation. The script attempts decryption with all provided master keys.
11182
* **Session salt** is used for stronger ephemeral key derivation. If you require persistent encrypted artifacts across runs, use per-key persistent salts stored with the ciphertext.
112-
* **Encrypted personas/inactive storage**: the simulator supports encrypting `personas.json` and `inactive.json` on write and decrypting on load — enable this to protect persona metadata at rest.
83+
* **Encrypted personas/inactive storage**: The simulator supports encrypting `personas.json` and `inactive.json` on write and decrypting on load — enable this to protect persona metadata at rest.
11384
* **Never commit** `.env`, `key.txt`, or any file containing real private keys to version control.
11485
* Consider using HashiCorp Vault, AWS Secrets Manager, or similar for production secrets.
11586

0 commit comments

Comments
 (0)