Add Salvium documentation and configuration examples

Co-authored-by: t1amak <57602242+t1amak@users.noreply.github.com>
2025-08-30 20:47:59 +00:00
parent 944b41b35c
commit cc458741a7
2 changed files with 280 additions and 0 deletions
--- a/config_examples/salvium.json
+++ b/config_examples/salvium.json
@@ -0,0 +1,165 @@
+{
+    "poolHost": "your.salvium.pool.host",
+	
+    "coin": "Salvium",
+    "symbol": "SAL",
+    "coinUnits": 1000000000000,
+    "coinDecimalPlaces": 12,
+    "coinDifficultyTarget": 120,
+    "blockchainExplorer": "https://explorer.salvium.io/block/{id}",
+    "transactionExplorer": "https://explorer.salvium.io/tx/{id}",
+
+    "daemonType": "default",
+    "cnAlgorithm": "cryptonight",
+    "cnVariant": 0,
+    "cnBlobType": 0,
+
+    "logging": {
+        "files": {
+            "level": "info",
+            "directory": "logs",
+            "flushInterval": 5
+        },
+        "console": {
+            "level": "info",
+            "colors": true
+        }
+    },
+
+    "salvium": {
+        "enabled": true,
+        "addressSeparator": "+",
+        "heights": {
+            "audit_phase1": 815,
+            "audit_phase2": 900,
+            "audit_phase3": 950,
+            "audit_complete": 1000,
+            "require_dual_login": 1050,
+            "carrot": 1100
+        },
+        "addressPrefixes": {
+            "cryptonote": {
+                "public": "0x3ef318",
+                "integrated": "0x55ef318",
+                "subaddress": "0xf5ef318"
+            },
+            "carrot": {
+                "public": "0x180c96",
+                "integrated": "0x2ccc96",
+                "subaddress": "0x314c96"
+            }
+        },
+        "carrotPoolAddress": "SC1_YOUR_POOL_CARROT_ADDRESS_HERE",
+        "carrotDonationAddress": "SC1_YOUR_DONATION_CARROT_ADDRESS_HERE"
+    },
+
+    "childPools": null,
+    "poolServer": {
+        "enabled": true,
+        "mergedMining": false,
+        "clusterForks": "auto",
+        "poolAddress": "SaLv_YOUR_POOL_CRYPTONOTE_ADDRESS_HERE",
+        "intAddressPrefix": null,
+        "blockRefreshInterval": 600,
+        "minerTimeout": 600,
+        "ports": [
+            {
+                "port": 3333,
+                "difficulty": 5000,
+                "desc": "Low end hardware"
+            },
+            {
+                "port": 4444,
+                "difficulty": 15000,
+                "desc": "Mid range hardware"
+            },
+            {
+                "port": 5555,
+                "difficulty": 25000,
+                "desc": "High end hardware"
+            }
+        ],
+        "varDiff": {
+            "minDiff": 5000,
+            "maxDiff": 100000000,
+            "targetTime": 120,
+            "retargetTime": 30,
+            "variancePercent": 30,
+            "maxJump": 100
+        },
+        "paymentId": {
+            "addressSeparator": "+"
+        },
+        "fixedDiff": {
+            "enabled": true,
+            "addressSeparator": "."
+        },
+        "shareTrust": {
+            "enabled": true,
+            "min": 10,
+            "stepDown": 3,
+            "threshold": 10,
+            "penalty": 30
+        },
+        "banning": {
+            "enabled": true,
+            "time": 600,
+            "invalidPercent": 80,
+            "checkThreshold": 30
+        }
+    },
+
+    "payments": {
+        "enabled": true,
+        "interval": 600,
+        "maxAddresses": 50,
+        "mixin": 16,
+        "priority": 0,
+        "transferFee": 1000000000,
+        "dynamicTransferFee": true,
+        "minerPayFee": true,
+        "minPayment": 1000000000000,
+        "maxTransactionAmount": 100000000000000,
+        "denomination": 1000000000
+    },
+
+    "blockUnlocker": {
+        "enabled": true,
+        "interval": 30,
+        "depth": 60,
+        "poolFee": 1.0,
+        "devDonation": 0.1,
+        "networkFee": 0.0
+    },
+
+    "api": {
+        "enabled": true,
+        "hashrateWindow": 600,
+        "updateInterval": 5,
+        "bindIp": "0.0.0.0",
+        "port": 8070,
+        "blocks": 30,
+        "payments": 30,
+        "password": "your_api_password",
+        "ssl": false,
+        "trustProxyIP": true
+    },
+
+    "daemon": {
+        "host": "127.0.0.1",
+        "port": 11812
+    },
+
+    "wallet": {
+        "host": "127.0.0.1",
+        "port": 11813
+    },
+
+    "redis": {
+        "host": "127.0.0.1",
+        "port": 6379,
+        "auth": null,
+        "db": 0,
+        "cleanupInterval": 15
+    }
+}
--- a/docs/SALVIUM.md
+++ b/docs/SALVIUM.md
@@ -0,0 +1,115 @@
+# Salvium Fork Mechanics
+
+This pool implementation includes support for Salvium's unique height-triggered hard fork mechanics. These features are strictly opt-in and maintain 100% backward compatibility with existing coins.
+
+## Configuration
+
+To enable Salvium fork mechanics, add the following to your `config.json`:
+
+```json
+{
+  "coin": "Salvium",
+  "symbol": "SAL",
+  "salvium": {
+    "enabled": true,
+    "addressSeparator": "+",
+    "heights": {
+      "audit_phase1": 815,
+      "audit_phase2": 900,
+      "audit_phase3": 950,
+      "audit_complete": 1000,
+      "require_dual_login": 1050,
+      "carrot": 1100
+    },
+    "addressPrefixes": {
+      "cryptonote": {
+        "public": "0x3ef318",
+        "integrated": "0x55ef318", 
+        "subaddress": "0xf5ef318"
+      },
+      "carrot": {
+        "public": "0x180c96",
+        "integrated": "0x2ccc96",
+        "subaddress": "0x314c96"
+      }
+    },
+    "carrotPoolAddress": "SC1...",
+    "carrotDonationAddress": "SC1..."
+  }
+}
+```
+
+## Fork Mechanics by Height
+
+### Phase 1: Symbol Transition (Height 815)
+- Pool recognizes ticker change from "SAL" to "SAL1"
+- Update config `symbol` field accordingly
+
+### Phase 2: Payout Blackout (Heights 815-999)
+- Miner shares continue to be accepted and credited
+- **Payment processor is disabled** - no payout transactions are sent
+- Balances accumulate normally
+
+### Phase 3: Payout Resume (Heights 1000-1049)
+- Normal payment processing resumes
+- Accumulated balances from blackout period are paid out
+
+### Phase 4: Dual Address Required (Heights 1050-1099)
+- Miners **must** provide dual address format: `[cryptonote_address]+[carrot_address]`
+- Pool rejects single address logins with clear error message
+- Payouts still sent to cryptonote address
+
+### Phase 5: Carrot Payouts (Heights 1100+)
+- All payouts switch permanently to carrot addresses
+- Pool fees/donations use `carrotPoolAddress` and `carrotDonationAddress`
+
+## Miner Instructions
+
+### Before Height 1050
+Use standard cryptonote address:
+```
+your_cryptonote_address
+```
+
+### Heights 1050+
+Use dual address format:
+```
+your_cryptonote_address+your_carrot_address
+```
+
+Example:
+```
+SaLv123...abc+SC1def...xyz
+```
+
+## Address Validation
+
+The pool validates addresses against specific Base58 prefixes:
+
+**Cryptonote Addresses:**
+- Public: 0x3ef318 (SaLv)
+- Integrated: 0x55ef318 (SaLvi)  
+- Subaddress: 0xf5ef318 (SaLvs)
+
+**Carrot Addresses:**
+- Public: 0x180c96 (SC1)
+- Integrated: 0x2ccc96 (SC1i)
+- Subaddress: 0x314c96 (SC1s)
+
+## Backward Compatibility
+
+- **Zero impact** on non-Salvium pools
+- All logic gated behind `config.salvium.enabled` flag
+- Standard cryptonote pools operate unchanged
+- No performance impact when disabled
+
+## Implementation Details
+
+The fork mechanics are implemented in:
+
+- `lib/utils.js`: Core Salvium utility functions
+- `lib/pool.js`: Dual address login validation  
+- `lib/paymentProcessor.js`: Payout blackout and address switching
+- `config.json`: Configuration schema and examples
+
+All changes maintain the existing API and behavior for non-Salvium use cases.