Skip to content

Commit e10af2c

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

File tree

1 file changed

+70
-37
lines changed

1 file changed

+70
-37
lines changed

‎README.md‎

Lines changed: 70 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11

22
# ⚡ Celo Wallet Simulator
33

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

69
A lightweight **wallet activity simulator** for the **Celo blockchain**, designed for:
710

@@ -14,15 +17,20 @@ A lightweight **wallet activity simulator** for the **Celo blockchain**, designe
1417

1518
## 📦 Features
1619

17-
* ✅ **In-memory encrypted private keys** (AES-256-GCM): Private keys are kept encrypted in memory and decrypted only when required for signing.
20+
* ✅ **In-memory encrypted private keys** (AES-256-GCM): Private keys are encrypted in memory and decrypted only when signing transactions.
1821
* ✅ **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.
22+
* ✅ **Persona-driven wallet behavior** (`personas.json`): Configurable parameters include `idleBias`, `pingBias`, `activeHours`, `avgWait`, `retryBias`, `minAmount`, `maxAmount`, `cooldownAfterFail`, `maxNonce`, and `device-agent`.
23+
* ✅ **Device-agent support**: Per-wallet `User-Agent` and simulated latency for fingerprint diversity.
2124
* ✅ **Configurable wait logic**: Adaptive/random spacing to mimic organic activity.
2225
* ✅ **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.
26+
* ✅ **Proxy auto-refresh**: Proxies reload every **15 minutes** without restart.
27+
* ✅ **Inactive wallet refresh**: Wallets marked inactive are refreshed every **30 minutes** and re-activated once their active hours are reached.
28+
* ✅ **Adaptive activity patterns**: Dynamic `idleBias` adjusting to success/failure rates.
29+
* ✅ **Transaction retry logic**: Governed by persona `retryBias` and cooldown parameters, with randomized wait times.
2430
* ✅ **Structured CSV logging**: Daily rotated `tx_log_YYYY-MM-DD.csv` with buffered flushes.
25-
* ✅ **Graceful shutdown**: Signal handlers flush logs and persist personas.
31+
* ✅ **Log retention & cleanup**: Old logs (older than 3 days) auto-deleted. Supports `--clear-logs` flag for full cleanup.
32+
* ✅ **Resource & error monitoring**: Logs memory usage periodically; robust uncaught error handling.
33+
* ✅ **Graceful shutdown**: Signal handlers flush logs and persist persona state on exit.
2634

2735
---
2836

@@ -38,19 +46,19 @@ A lightweight **wallet activity simulator** for the **Celo blockchain**, designe
3846

3947
2. **Configure environment**
4048

41-
Create a local `.env` (for testing only — do NOT commit) with at minimum:
49+
Create `.env` (for testing only — do NOT commit):
4250

4351
```bash
4452
PRIVATE_KEYS="0xabc...\n0xdef..." # one key per line
4553
MASTER_KEY="your_master_passphrase"
4654
BACKUP_KEYS="oldMaster1,oldMaster2" # optional
4755
```
4856

49-
Or set these as OS-level environment variables (recommended for production).
57+
Or set them as OS-level environment variables (recommended for production).
5058

5159
3. **(Optional) Add legacy key file**
5260

53-
If you prefer legacy workflow, create `key.txt` with one private key per line — but `index.js` reads `PRIVATE_KEYS` env by default.
61+
Create `key.txt` with one private key per line (optional — overridden by `PRIVATE_KEYS`).
5462

5563
4. **Run the simulator**
5664

@@ -60,73 +68,98 @@ A lightweight **wallet activity simulator** for the **Celo blockchain**, designe
6068

6169
5. **Stop gracefully**
6270

63-
Press `Ctrl+C` — the process will flush logs and save persona state before exit.
71+
Press `Ctrl+C` — logs will flush, and persona state will persist.
6472

6573
---
6674

6775
## 🧩 Configuration & Files
6876

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`.
77+
* `index.js` — main runtime engine (encryption, personas, RPC/proxy logic, tx loop).
78+
* `personas.json` — persona defaults (auto-created if missing); supports encrypted storage.
79+
* `inactive.json` — stores addresses outside active hours (optional encryption).
80+
* `proxy.txt` — optional: one proxy URL per line (`http(s)://host:port` or `socks5://host:port`).
81+
* `key.txt` — legacy: one private key per line (optional).
82+
* `tx_log_YYYY-MM-DD.csv` — daily logs with: `timestamp,wallet,tx_hash,nonce,gas_used,gas_price_gwei,fee_celo,status,action`.
83+
84+
---
85+
86+
### Persona Example
87+
88+
```json
89+
{
90+
"0xabc...": {
91+
"idleBias": 0.12,
92+
"pingBias": 0.06,
93+
"minAmount": 0.0001,
94+
"maxAmount": 0.01,
95+
"activeHours": [2, 22],
96+
"cooldownAfterFail": 90,
97+
"avgWait": 45,
98+
"retryBias": 0.2,
99+
"maxNonce": 560,
100+
"failCount": 0,
101+
"lastFailAt": null,
102+
"deviceAgent": {
103+
"userAgent": "Chrome/102.0 (Windows NT 10.0)",
104+
"latency": 120
105+
}
106+
}
107+
}
108+
```
75109

76110
---
77111

78112
## 🔒 Security Notes
79113

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.
82-
* **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.
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.
84-
* **Never commit** `.env`, `key.txt`, or any file containing real private keys to version control.
85-
* Consider using HashiCorp Vault, AWS Secrets Manager, or similar for production secrets.
114+
* **MASTER_KEY** encrypts private keys and is required on startup.
115+
* **BACKUP_KEYS** allow decryption of old encrypted blobs after rotation.
116+
* **Session salt** strengthens ephemeral key derivation; store salts for persistence.
117+
* **Encrypted personas/inactive storage**: optionally encrypt on write/load.
118+
* **Never commit** `.env`, `key.txt`, or any private key files.
119+
* Use secret managers like HashiCorp Vault or AWS Secrets Manager in production.
86120

87121
---
88122

89123
## 🕵️ Device Agent & Fake Latency
90124

91-
* Each persona can include a `deviceAgent` object containing a `userAgent` string and a `latency` value (ms). The simulator uses `userAgent` when making HTTP/RPC calls where custom headers are supported and applies `latency` as a simulated network delay before/after RPC calls to diversify network footprints.
92-
* Device agents are persisted in personas (and can be encrypted on disk) so wallets keep consistent fingerprinting unless rotated deliberately.
125+
* Per-wallet `deviceAgent` settings allow unique `User-Agent` strings and simulated latency to diversify network behavior.
126+
* Device agents are persisted in personas unless rotated manually.
93127

94128
---
95129

96130
## ⚙️ Adaptive Activity Patterns
97131

98-
* The simulator keeps simple success/failure counters per persona (`txSuccessCount`, `txFailCount`) and uses those to **adjust `idleBias` dynamically**.
99-
* If a wallet experiences repeated failures, `idleBias` increases to reduce activity (saving gas and avoiding repeated failures). When success rate improves, `idleBias` lowers to resume normal activity.
132+
* Success/failure counters (`txSuccessCount`, `txFailCount`) dynamically adjust `idleBias`.
133+
* Repeated failures increase `idleBias` and reduce activity; success lowers it to normal levels.
100134

101135
---
102136

103137
## 📈 Logging & Observability
104138

105-
* Transaction logs are buffered and flushed to daily CSV files every 5 minutes (configurable).
106-
* Consider integrating metrics or a dashboard (Prometheus / Grafana) for real-time monitoring and alerts (RPC failures, wallet depletion, repeated tx failures).
139+
* Logs buffered and flushed every 5 minutes.
140+
* Old logs auto-deleted after 3 days; `--clear-logs` flag purges logs.
141+
* Consider metrics dashboards (Prometheus / Grafana) for real-time monitoring.
107142

108143
---
109144

110-
## 🛠️ Extensibility & Next Steps
111-
112-
Suggested improvements:
145+
## 🛠️ Extensibility
113146

114-
* Encrypted persona & inactive storage (implemented/optional)
115-
* Persistent per-key salts for long-term encrypted artifacts
116-
* Dashboard & metrics for live monitoring
117-
* Stable proxy-per-wallet assignment to simulate consistent geolocation
147+
* Encrypted persona/inactive storage
148+
* Persistent per-key salts
149+
* Dashboard for metrics
150+
* Stable proxy-per-wallet assignment for location simulation
118151

119152
---
120153

121154
## 🤝 Contributing
122155

123-
Contributions welcome. Fork → branch → PR. Include tests and documentation for runtime changes.
156+
Fork → branch → PR. Include tests and documentation.
124157

125158
---
126159

127160
## ⚠️ Disclaimer
128161

129-
This tool is for research, testing, and education. Do **not** use it for spam, Sybil attacks, or behavior that violates network terms. Use testnets wherever possible.
162+
For research, testing, and education only. Avoid spam/Sybil attacks. Use testnets where possible.
130163

131164
---
132165

0 commit comments

Comments
 (0)