several updates

.gitignore

@@ -1,4 +1,4 @@
 
-
 node_modules
-.env
+.env
+config/env

Dockerfile

@@ -1,4 +1,4 @@
-FROM node:fermium
+FROM node:24-bookworm-slim
 
 WORKDIR /app
 
@@ -13,4 +13,4 @@ COPY ./config.js ./config.js
 
 EXPOSE 3000
 
-CMD node index.js
+CMD ["node", "index.js"]

README.md

@@ -2,49 +2,94 @@
 
 ## Description
 
-This is a simple NodsJS Express server to fetch information on Syscoin.
+This is a simple Node.js Express server to fetch information on Syscoin.
 
-## Endpoints
+## Configuration
 
-Host: https://info.syscoin.org/
+All runtime settings live under `config/`:
 
-### `GET /totalsupply`
+| File | Purpose |
+|------|---------|
+| `config/.env.example` | Template — copy to `config/env` and edit |
+| `config/env` | Your local secrets and overrides (not committed) |
+| `config.js` | Defaults (e.g. SyscoinVaultManager address) |
 
-- This returns total supply calculated on both UTXO and NEVM blockchain in plaintext.
-
-### `GET /triggerRecordSupply`
+**Setup:**
 
-- Normally total supply is calculated and recorded when new block hash is detected.
-- This endpoints acts as manual trigger in calculation.
-
-### `GET /health`
+```bash
+cp config/.env.example config/env
+# Edit config/env with your RPC credentials
+```
 
-- This is a health check endpoint. Useful for monitoring if API is running.
+- **Local:** `node index.js` loads `config/env` via dotenv.
+- **Docker:** `docker compose` injects the same file (`env_file: config/env` in `docker-compose.yml`).
 
-## Syscoin Core (`/syscoin-core`)
+This service expects a **Syscoin Core node already running** on the host (or elsewhere) and reachable via RPC. UTXO supply uses `gettxoutsetinfo`; NEVM components come from the public explorer API.
 
-- Dockerized version of the Syscoin Daemon
-- JSON RPC is used by the API in retrieving UTXO supply
+### Environment variables
 
-## API Environment Variables (Required\*)
+**Required** (in `config/env`):
 
-- `SYSCOIN_CORE_RPC_HOST` ex. `localhost`
-- `SYSCOIN_CORE_RPC_PORT` ex. `8370`
-- `SYSCOIN_CORE_RPC_PASSWORD` - password for auth to RPC
-- `SYSCOIN_CORE_RPC_USERNAME` - username for auth to RPC
+- `SYSCOIN_CORE_RPC_HOST` — e.g. `localhost` (local) or `host.docker.internal` (Docker on Linux)
+- `SYSCOIN_CORE_RPC_PORT` — e.g. `8370`
+- `SYSCOIN_CORE_RPC_USERNAME` — RPC username
+- `SYSCOIN_CORE_RPC_PASSWORD` — RPC password
 
-An `.env.example` is provided for convenience.
+**Optional:**
 
+- `SYSCOIN_VAULT_MANAGER` — override the SyscoinVaultManager contract address (default in `config.js`)
+- `PORT` — HTTP listen port (default `3000`)
+- `POLLING_INTERVAL_SECONDS` — how often supply is recalculated (default `30`)
+- `TOTAL_SUPPLY_URL` — primary NEVM coinsupply explorer URL (default `explorer1.syscoin.org`)
+- `TOTAL_SUPPLY_URL_BACKUP` — fallback coinsupply URL if primary fails (default `explorer2.syscoin.org`)
 
-You can generate password and username:
+Generate RPC credentials for `syscoin.conf`:
 
 ```bash
 curl -sSL https://raw.githubusercontent.com/syscoin/syscoin/master/share/rpcauth/rpcauth.py | python - <username>
 ```
 
-For more information you can check it here: https://github.com/syscoin/docker-syscoin-core#usage
+See also: https://github.com/syscoin/docker-syscoin-core#usage
 
 ## Syscoin Vault Manager
 
-Please refer to `config.js` for the current official address of SyscoinVaultManager contract.
+The official contract address is defined in `config.js` and can be overridden via `SYSCOIN_VAULT_MANAGER` in `config/env`.
+
+```
+total supply = UTXO supply + NEVM supply − vault contract balance
+```
+
+## Endpoints
+
+Host: https://info.syscoin.org/
+
+### `GET /totalsupply`
+
+Returns total supply (UTXO + NEVM - minus vault balance) as plain text.
+
+### `GET /circulatingsupply`
+
+Returns circulating supply as plain text.
+
+### `GET /triggerRecordSupply`
+
+Manually triggers an immediate supply recalculation. On startup and by default every 30 seconds, supply is refreshed automatically via polling (`POLLING_INTERVAL_SECONDS` in `config/env`).
+
+### `GET /health`
+
+Simple liveness check (`OK`).
+
+### `GET /status`
+
+Detailed status including last recorded values and any fetch errors.
+
+## Docker
+
+```bash
+cp config/.env.example config/env
+# Edit config/env (use host.docker.internal for SYSCOIN_CORE_RPC_HOST on Linux)
+
+docker compose up -d --build
+```
 
+The API is published on host port `3050` (maps to container port `3000`).

config.js

@@ -1,6 +1,7 @@
 class CONFIGURATION {
   constructor() {
-    this.SyscoinVaultManager = "0x7904299b3D3dC1b03d1DdEb45E9fDF3576aCBd5f";
+    this.SyscoinVaultManager =
+      process.env.SYSCOIN_VAULT_MANAGER || "0x7904299b3D3dC1b03d1DdEb45E9fDF3576aCBd5f";
   }
 }
 

config/.env.example

@@ -0,0 +1,29 @@
+# Copy this file to config/env and fill in your values:
+#   cp config/.env.example config/env
+#
+# Used by:
+#   - Local runs: loaded via dotenv in index.js
+#   - Docker: injected by docker-compose (env_file: config/env)
+
+# Syscoin Core RPC (required)
+SYSCOIN_CORE_RPC_HOST=localhost
+SYSCOIN_CORE_RPC_PORT=8370
+SYSCOIN_CORE_RPC_USERNAME=user
+SYSCOIN_CORE_RPC_PASSWORD=pass
+
+# Docker on Linux: reach syscoind on the host (uncomment and comment localhost above)
+# SYSCOIN_CORE_RPC_HOST=host.docker.internal
+
+# Optional: override the SyscoinVaultManager contract address.
+# Defaults to the official address in config.js if unset.
+# SYSCOIN_VAULT_MANAGER=0x7904299b3D3dC1b03d1DdEb45E9fDF3576aCBd5f
+
+# Optional: HTTP listen port (default 3000)
+# PORT=3000
+
+# Optional: supply polling interval in seconds (default 30)
+# POLLING_INTERVAL_SECONDS=30
+
+# Optional: NEVM coinsupply explorer URLs (primary then backup on HTTP/parse failure)
+# TOTAL_SUPPLY_URL=https://explorer1.syscoin.org/api?module=stats&action=coinsupply
+# TOTAL_SUPPLY_URL_BACKUP=https://explorer2.syscoin.org/api?module=stats&action=coinsupply

docker-compose.yml

@@ -0,0 +1,20 @@
+#version: '3.8'
+
+# NOTE: Use Docker's default bridge (docker0, 172.17.0.0/16) so RPC
+# from the container matches syscoind rpcallowip=172.17.0.0/16 on the host.
+# Reach Syscoin Core via host.docker.internal -> host gateway (172.17.0.1).
+
+services:
+  api:
+    container_name: supply-api
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: syscoin/sys-supply-api
+    restart: always
+    network_mode: bridge
+    env_file: config/env
+    extra_hosts:
+      - 'host.docker.internal:host-gateway'
+    ports:
+      - 3050:3000