diff --git a/COMMUNITY_NOTES.md b/COMMUNITY_NOTES.md new file mode 100644 index 0000000..fa2a55d --- /dev/null +++ b/COMMUNITY_NOTES.md @@ -0,0 +1,23 @@ +# Community Notes + +## Frequently Observed Issues + +### Synchronization Delays + +Observed cases where faucet transactions appear in history before balances are reflected on the dashboard. + +### Dashboard Cache + +Refreshing the dashboard may be required after transactions are processed. + +### X Verification + +Users should complete posting and verification steps in the correct order and allow time for indexing. + +### Support Requests + +Useful information when reporting issues: +- Wallet address +- Username +- Screenshots +- Error messages diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000..35e348d --- /dev/null +++ b/FAQ.md @@ -0,0 +1,39 @@ +# FAQ + +## Why is my balance still zero after a faucet claim? + +Possible reasons: +- Synchronization delay +- Dashboard cache +- Transaction indexing not completed yet + +Wait a short time, refresh the dashboard, and verify the transaction status using the currently recommended explorer or official community instructions. + +## Where can I find the correct RPC endpoint? + +Use the official QoreChain documentation, repository notes, or current team announcements for the latest RPC endpoint and chain configuration values. + +Avoid relying on old screenshots, cached messages, or unverified third-party endpoint lists. + +## Why is X verification failing? + +Common causes: +- Verification performed too late +- Post not indexed yet +- Verification steps completed out of order +- Account or post visibility settings preventing verification + +Repeat the steps carefully and allow time for indexing before retrying. + +## Dashboard not loading? + +Check: +- Expected dashboard port +- Container status +- Firewall configuration +- Docker logs +- Whether the node is running in local-only mode + +## Should I use these notes for production setup? + +Treat this FAQ as community onboarding help. For production or mainnet-sensitive steps, confirm all values with official QoreChain sources first. diff --git a/INSTALLATION_GUIDE.md b/INSTALLATION_GUIDE.md new file mode 100644 index 0000000..9732555 --- /dev/null +++ b/INSTALLATION_GUIDE.md @@ -0,0 +1,128 @@ +# QoreChain Light Node Installation Guide + +This guide explains the basic setup flow for running a QoreChain Light Node. + +> This is a community documentation contribution. Always check official QoreChain sources and current announcements for production instructions. + +--- + +## 1. Requirements + +Before starting, make sure your system has: + +- Linux VPS or local Linux environment +- Go installed +- Docker and Docker Compose installed +- Git installed +- Basic terminal access + +For VPS usage, Ubuntu is commonly used by beginners. + +--- + +## 2. Clone the Repository + +```bash +git clone https://github.com/qorechain/qorechain-lightnode.git +cd qorechain-lightnode +``` + +If you are testing changes from a fork, replace the repository URL with the fork URL. + +--- + +## 3. Build the Light Node + +### SX Edition + +The SX edition is designed for server / VPS usage. + +```bash +CGO_ENABLED=1 go build -o build/lightnode-sx ./cmd/lightnode-sx/ +``` + +### UX Edition + +The UX edition includes a dashboard experience. + +```bash +CGO_ENABLED=1 go build -o build/lightnode-ux ./cmd/lightnode-ux/ +``` + +--- + +## 4. Run Onboarding + +```bash +build/lightnode-sx onboard +``` + +The onboarding wizard may ask for: + +- Chain RPC endpoint +- Private key or new key generation +- Node configuration details + +If the network endpoint is not available yet, local-only mode can be used for testing. + +--- + +## 5. Start the Node + +```bash +build/lightnode-sx start +``` + +--- + +## 6. Docker Setup + +Start the SX edition: + +```bash +docker compose up lightnode-sx +``` + +Start the UX edition: + +```bash +docker compose up lightnode-ux +``` + +Run in background: + +```bash +docker compose up -d +``` + +--- + +## 7. Check Logs + +```bash +docker compose logs -f +``` + +--- + +## 8. Restart Services + +```bash +docker compose restart +``` + +--- + +## 9. Verify PQC Self-Test + +```bash +lightnode-sx selftest +``` + +This verifies that the post-quantum cryptography stack is working correctly. + +--- + +## 10. Notes + +This guide is intended for learning and operator onboarding. Network-specific values such as RPC endpoints, chain IDs, ports, and production settings should be verified against current official QoreChain sources before use. diff --git a/OPERATOR_JOURNAL.md b/OPERATOR_JOURNAL.md new file mode 100644 index 0000000..fd42be2 --- /dev/null +++ b/OPERATOR_JOURNAL.md @@ -0,0 +1,29 @@ +# Operator Journal + +## VPS Deployment Notes + +### Environment + +- DigitalOcean VPS +- Ubuntu Linux +- Docker & Docker Compose + +### Initial Deployment + +Status: Successful + +Observations: +- Containers started successfully +- Dashboard reachable on configured port +- Node services operating normally + +## Lessons Learned + +- Verify open ports before troubleshooting +- Check container status first +- Keep configuration backups +- Monitor logs regularly + +## Future Notes + +This file will be updated with operational experiences, infrastructure observations, and deployment lessons. diff --git a/README.md b/README.md index 561c2ca..83b95cb 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Light node client for the QoreChain network. Provides two editions: - Post-quantum cryptography support (Dilithium-5) - **Interactive onboarding wizard** that runs a PQC self-test, accepts the chain RPC endpoint, and imports or generates a Dilithium-5 validator key - **Local-only mode** so the node can prove its PQC stack works even before the chain itself is deployed -- **Live PQC self-test** — `lightnode-sx selftest` runs keygen → sign → verify → tamper-detection in under a second +- **Live PQC self-test** — `lightnode-sx selftest` runs keygen -> sign -> verify -> tamper-detection in under a second ## Quick Start @@ -37,7 +37,7 @@ build/lightnode-sx start ``` The wizard asks for: -- **Chain RPC endpoint** — paste the URL (e.g. `https://rpc.qorechain.io:26657`), or leave blank to run in local-only mode while the chain itself is still being deployed. +- **Chain RPC endpoint** — paste the official RPC URL when available, or leave blank to run in local-only mode while the chain itself is still being deployed. - **Private key** — paste a hex-encoded Dilithium-5 key, or type `g` to generate a fresh one on this node. If you leave the endpoint blank the daemon will start in **local-only mode** — the PQC stack is fully exercised and the web dashboard shows a banner explaining the state. Re-run `onboard` once the chain is live to point at a real RPC. @@ -67,9 +67,17 @@ lightnode-sx selftest Runs 5 checks: keygen, sign, verify-valid, reject-tampered-sig, reject-tampered-msg. +## Additional Documentation + +- [Installation Guide](./INSTALLATION_GUIDE.md) +- [FAQ](./FAQ.md) +- [Community Notes](./COMMUNITY_NOTES.md) +- [Operator Journal](./OPERATOR_JOURNAL.md) +- [Example Configuration](./config.example.toml) + ## Configuration -See `config.example.toml` for all available options. +See `config.example.toml` for available example options. Always verify network values against current official QoreChain sources before using them in production. ## License diff --git a/config.example.toml b/config.example.toml new file mode 100644 index 0000000..92e6e04 --- /dev/null +++ b/config.example.toml @@ -0,0 +1,15 @@ +# QoreChain Light Node example configuration + +[network] +# Replace this placeholder with the current official QoreChain RPC endpoint. +rpc_endpoint = "" + +# Set this according to the active network configuration. +chain_id = "" + +[node] +# Use "sx" for server deployments or "ux" for dashboard mode. +edition = "sx" + +[logging] +level = "info"