You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
*`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
+
}
69
103
```
70
104
71
105
---
72
106
73
-
## ⚠️ Disclaimer
107
+
## 🔒 Security Notes
74
108
75
-
This project is provided for **educational and development purposes only**.
76
-
It is intended to support Celo developers and infrastructure teams in:
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.
111
+
***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.
113
+
***Never commit**`.env`, `key.txt`, or any file containing real private keys to version control.
114
+
* Consider using HashiCorp Vault, AWS Secrets Manager, or similar for production secrets.
77
115
78
-
* Testing RPC endpoints
79
-
* Simulating transaction activity
80
-
* Analyzing network performance
116
+
---
117
+
118
+
## 🕵️ Device Agent & Fake Latency
81
119
82
-
It should **not** be used for spam, Sybil attacks, or any form of abuse.
120
+
* 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.
121
+
* Device agents are persisted in personas (and can be encrypted on disk) so wallets keep consistent fingerprinting unless rotated deliberately.
83
122
84
123
---
124
+
125
+
## ⚙️ Adaptive Activity Patterns
126
+
127
+
* The simulator keeps simple success/failure counters per persona (`txSuccessCount`, `txFailCount`) and uses those to **adjust `idleBias` dynamically**.
128
+
* 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.
129
+
130
+
---
131
+
132
+
## 📈 Logging & Observability
133
+
134
+
* Transaction logs are buffered and flushed to daily CSV files every 5 minutes (configurable).
135
+
* Consider integrating metrics or a dashboard (Prometheus / Grafana) for real-time monitoring and alerts (RPC failures, wallet depletion, repeated tx failures).
136
+
137
+
---
138
+
139
+
## 🛠️ Extensibility & Next Steps
140
+
141
+
Suggested improvements:
142
+
143
+
* Encrypted persona & inactive storage (implemented/optional)
144
+
* Persistent per-key salts for long-term encrypted artifacts
145
+
* Dashboard & metrics for live monitoring
146
+
* Stable proxy-per-wallet assignment to simulate consistent geolocation
147
+
148
+
---
149
+
150
+
## 🤝 Contributing
151
+
152
+
Contributions welcome. Fork → branch → PR. Include tests and documentation for runtime changes.
153
+
154
+
---
155
+
156
+
## ⚠️ Disclaimer
157
+
158
+
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.
159
+
160
+
---
161
+
162
+
## 📜 License
163
+
164
+
Licensed under the terms in the [LICENSE](LICENSE) file.
0 commit comments