docs: add comprehensive exchange integration guide

- Document network overview and confirmation requirements - Provide node setup instructions with Docker - Explain address generation for hot/cold wallets - Detail deposit monitoring via WebSocket and polling - Document withdrawal transaction building - Explain hybrid signature format (Ed25519 + Dilithium3) - Include complete API reference - Add security recommendations for exchange operations - Document testnet environment for testing
2026-01-10 06:20:35 +05:30 · 2026-01-10 06:20:35 +05:30 · 960c25eb8a
commit 960c25eb8a
parent 4a2825f516
1 changed files with 532 additions and 0 deletions
--- a/docs/EXCHANGE_INTEGRATION.md
+++ b/docs/EXCHANGE_INTEGRATION.md
@ -0,0 +1,532 @@
+# Synor Exchange Integration Guide
+
+This document provides technical specifications for cryptocurrency exchanges to integrate Synor (SYNOR) deposits, withdrawals, and trading.
+
+## Table of Contents
+
+1. [Network Overview](#network-overview)
+2. [Node Setup](#node-setup)
+3. [Address Generation](#address-generation)
+4. [Deposits](#deposits)
+5. [Withdrawals](#withdrawals)
+6. [Transaction Format](#transaction-format)
+7. [API Reference](#api-reference)
+8. [Security Considerations](#security-considerations)
+9. [Test Environment](#test-environment)
+
+---
+
+## Network Overview
+
+### Basic Information
+
+| Property | Value |
+|----------|-------|
+| **Name** | Synor |
+| **Symbol** | SYNOR |
+| **Decimals** | 8 |
+| **Smallest Unit** | soma (1 SYNOR = 10^8 somas) |
+| **Block Time** | ~10 seconds (DAG-based) |
+| **Consensus** | DAG-based PoW with SPECTRE ordering |
+| **Signature Scheme** | Hybrid Ed25519 + Dilithium3 (post-quantum) |
+
+### Network Types
+
+| Network | Address Prefix | Use Case |
+|---------|---------------|----------|
+| Mainnet | `synor1` | Production |
+| Testnet | `tsynor1` | Testing |
+
+### Confirmation Requirements
+
+| Amount | Recommended Confirmations |
+|--------|---------------------------|
+| < 100 SYNOR | 10 confirmations |
+| 100-10,000 SYNOR | 50 confirmations |
+| > 10,000 SYNOR | 100 confirmations |
+
+---
+
+## Node Setup
+
+### Hardware Requirements
+
+**Minimum:**
+- CPU: 4 cores
+- RAM: 8 GB
+- Storage: 100 GB SSD
+- Network: 100 Mbps
+
+**Recommended (Exchange):**
+- CPU: 8+ cores
+- RAM: 32 GB
+- Storage: 500 GB NVMe SSD
+- Network: 1 Gbps
+
+### Docker Deployment
+
+```yaml
+# docker-compose.yml
+version: '3.8'
+
+services:
+  synor-node:
+    image: synor/synord:latest
+    container_name: synor-exchange-node
+    restart: always
+    command:
+      - "run"
+      - "--p2p-port=16511"
+      - "--rpc-host=0.0.0.0"
+      - "--rpc-port=16110"
+      - "--ws-port=16111"
+      - "--seeds=seed1.synor.cc:16511,seed2.synor.cc:16511"
+    ports:
+      - "16511:16511"   # P2P (public)
+      - "127.0.0.1:16110:16110"  # RPC (internal only)
+      - "127.0.0.1:16111:16111"  # WebSocket (internal only)
+    volumes:
+      - synor-data:/data/synor
+    environment:
+      - RUST_LOG=info
+      - SYNOR_NETWORK=mainnet
+
+volumes:
+  synor-data:
+```
+
+### Node Health Check
+
+```bash
+# Check sync status
+curl -X POST http://localhost:16110 \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","method":"synor_getSyncStatus","params":[],"id":1}'
+
+# Response when synced:
+# {"result":{"synced":true,"currentBlock":1234567,"highestBlock":1234567}}
+```
+
+---
+
+## Address Generation
+
+### Address Format
+
+Synor addresses use Bech32m encoding:
+
+```
+synor1qz232pysw8kezv2f4qxnhdufrlx5cmq78522mpuf8x5qlxu6j8sgcp05get
+└────┘└──────────────────────────────────────────────────────────┘
+ HRP                    Base32-encoded payload
+```
+
+- **HRP (Human Readable Part):** `synor1` (mainnet) or `tsynor1` (testnet)
+- **Payload:** 32-byte Blake3 hash of the hybrid public key
+- **Checksum:** Bech32m checksum (6 characters)
+
+### Generating Addresses
+
+#### Using the CLI
+
+```bash
+# Generate new address
+synor-cli wallet new
+
+# Derive address from mnemonic
+synor-cli wallet recover --mnemonic "your 24 word phrase..."
+```
+
+#### Using the SDK (Rust)
+
+```rust
+use synor_crypto::{generate_keypair, public_key_to_address, Network};
+
+// Generate new keypair
+let keypair = generate_keypair();
+
+// Get address
+let address = public_key_to_address(&keypair.public_key, Network::Mainnet);
+// Returns: "synor1qz232pysw8kezv2f4qxnhdufrlx5cmq78522mpuf8x5qlxu6j8sgcp05get"
+```
+
+#### Using the SDK (JavaScript)
+
+```javascript
+import { createWallet, publicKeyToAddress } from '@synor/sdk';
+
+// Generate wallet from mnemonic
+const mnemonic = generateMnemonic(24);
+const wallet = await createWallet(mnemonic, '', 'mainnet');
+
+console.log(wallet.address);
+// "synor1qz232pysw8kezv2f4qxnhdufrlx5cmq78522mpuf8x5qlxu6j8sgcp05get"
+```
+
+### Address Validation
+
+```javascript
+// Validate address format
+function isValidSynorAddress(address) {
+  const mainnetRegex = /^synor1[a-z0-9]{58}$/;
+  const testnetRegex = /^tsynor1[a-z0-9]{59}$/;
+  return mainnetRegex.test(address) || testnetRegex.test(address);
+}
+```
+
+---
+
+## Deposits
+
+### Recommended Flow
+
+1. **Generate unique deposit address per user**
+2. **Monitor address via WebSocket or polling**
+3. **Wait for required confirmations**
+4. **Credit user account**
+
+### Monitoring Deposits
+
+#### WebSocket Subscription
+
+```javascript
+const ws = new WebSocket('ws://localhost:16111');
+
+ws.onopen = () => {
+  // Subscribe to address transactions
+  ws.send(JSON.stringify({
+    jsonrpc: '2.0',
+    method: 'synor_subscribeAddress',
+    params: ['synor1qz232...'],
+    id: 1
+  }));
+};
+
+ws.onmessage = (event) => {
+  const msg = JSON.parse(event.data);
+  if (msg.method === 'synor_addressNotification') {
+    const { txId, amount, confirmations } = msg.params;
+    console.log(`Deposit: ${amount} SYNOR (${confirmations} confirms)`);
+  }
+};
+```
+
+#### Polling Method
+
+```javascript
+async function checkDeposits(address, lastCheckedBlock) {
+  const response = await rpc('synor_getAddressTransactions', [
+    address,
+    { fromBlock: lastCheckedBlock, limit: 100 }
+  ]);
+
+  for (const tx of response.transactions) {
+    if (tx.type === 'receive' && tx.confirmations >= REQUIRED_CONFIRMS) {
+      await creditUser(address, tx.amount, tx.txId);
+    }
+  }
+
+  return response.currentBlock;
+}
+```
+
+### Deposit Transaction Example
+
+```json
+{
+  "txId": "a1b2c3d4e5f6...",
+  "type": "receive",
+  "amount": "100.00000000",
+  "from": "synor1sender...",
+  "to": "synor1exchange...",
+  "confirmations": 50,
+  "blockHash": "block1234...",
+  "timestamp": 1704067200
+}
+```
+
+---
+
+## Withdrawals
+
+### Recommended Flow
+
+1. **Validate withdrawal address**
+2. **Check exchange hot wallet balance**
+3. **Build and sign transaction**
+4. **Broadcast transaction**
+5. **Monitor confirmation status**
+6. **Update user withdrawal status**
+
+### Building a Withdrawal Transaction
+
+```javascript
+import { createSendTransactionHybrid, serializeTransaction } from '@synor/sdk';
+
+async function processWithdrawal(toAddress, amount, wallet) {
+  // Build signed transaction
+  const tx = await createSendTransactionHybrid(
+    wallet.address,  // From: exchange hot wallet
+    toAddress,       // To: user's address
+    amount,          // Amount in SYNOR (e.g., "100.5")
+    wallet           // Contains seed, keypair, dilithiumPublicKey
+  );
+
+  // Broadcast
+  const result = await rpc('synor_sendRawTransaction', [
+    serializeTransaction(tx)
+  ]);
+
+  return result.txId;
+}
+```
+
+### UTXO Consolidation
+
+For high-volume exchanges, periodically consolidate small UTXOs:
+
+```javascript
+async function consolidateUtxos(wallet) {
+  const utxos = await rpc('synor_getUtxos', [wallet.address]);
+
+  // Only consolidate if many small UTXOs
+  if (utxos.length < 100) return;
+
+  // Filter small UTXOs (< 1 SYNOR)
+  const smallUtxos = utxos.filter(u => parseFloat(u.amount) < 1);
+
+  if (smallUtxos.length < 50) return;
+
+  // Build consolidation transaction (send to self)
+  // ... transaction building code
+}
+```
+
+### Fee Estimation
+
+```javascript
+async function estimateFee(fromAddress, toAddress, amount) {
+  const result = await rpc('synor_estimateFee', [{
+    from: fromAddress,
+    to: toAddress,
+    amount: amount
+  }]);
+
+  return {
+    fee: result.fee,          // e.g., "0.00001000"
+    feePerByte: result.feePerByte,
+    estimatedSize: result.size  // Larger for hybrid signatures
+  };
+}
+```
+
+---
+
+## Transaction Format
+
+### Hybrid Signatures
+
+Synor uses **hybrid signatures** combining:
+
+1. **Ed25519** (64 bytes) - Classical elliptic curve
+2. **Dilithium3/ML-DSA-65** (~3.3 KB) - Post-quantum lattice-based
+
+Both signatures must verify for a transaction to be valid.
+
+### Transaction Structure
+
+```json
+{
+  "version": 1,
+  "inputs": [
+    {
+      "previousTxId": "abc123...",
+      "outputIndex": 0,
+      "signature": "ed25519_sig_hex",
+      "hybridSignature": {
+        "ed25519": "64_bytes_hex",
+        "dilithium": "3293_bytes_hex"
+      },
+      "publicKey": "ed25519_pubkey_32_bytes",
+      "dilithiumPublicKey": "dilithium_pubkey_1952_bytes"
+    }
+  ],
+  "outputs": [
+    {
+      "address": "synor1recipient...",
+      "amount": "10000000000"  // 100 SYNOR in somas
+    }
+  ],
+  "lockTime": 0,
+  "isHybrid": true
+}
+```
+
+### Transaction Size
+
+Due to Dilithium signatures, Synor transactions are larger than Bitcoin:
+
+| Component | Size (bytes) |
+|-----------|-------------|
+| Base transaction | ~50 |
+| Per input (hybrid) | ~5,500 |
+| Per output | ~40 |
+
+**Example:** 2 inputs, 2 outputs ≈ 11,180 bytes
+
+---
+
+## API Reference
+
+### JSON-RPC Endpoint
+
+- **HTTP:** `http://localhost:16110`
+- **WebSocket:** `ws://localhost:16111`
+
+### Common Methods
+
+#### synor_getBlockCount
+```json
+{"jsonrpc":"2.0","method":"synor_getBlockCount","params":[],"id":1}
+// Response: {"result": 1234567}
+```
+
+#### synor_getBalance
+```json
+{"jsonrpc":"2.0","method":"synor_getBalance","params":["synor1..."],"id":1}
+// Response: {"result": {"confirmed": "1000.50000000", "pending": "10.00000000"}}
+```
+
+#### synor_getUtxos
+```json
+{"jsonrpc":"2.0","method":"synor_getUtxos","params":["synor1..."],"id":1}
+// Response: {"result": [{"txId": "...", "outputIndex": 0, "amount": "100.00000000"}]}
+```
+
+#### synor_sendRawTransaction
+```json
+{"jsonrpc":"2.0","method":"synor_sendRawTransaction","params":["serialized_tx"],"id":1}
+// Response: {"result": {"txId": "abc123..."}}
+```
+
+#### synor_getTransaction
+```json
+{"jsonrpc":"2.0","method":"synor_getTransaction","params":["txId"],"id":1}
+// Response: {"result": {"txId": "...", "confirmations": 50, ...}}
+```
+
+#### synor_getAddressTransactions
+```json
+{"jsonrpc":"2.0","method":"synor_getAddressTransactions","params":["synor1...", 100],"id":1}
+// Response: {"result": [{"txId": "...", "type": "receive", ...}]}
+```
+
+---
+
+## Security Considerations
+
+### Hot/Cold Wallet Architecture
+
+```
+                    ┌─────────────────┐
+                    │   Cold Storage   │
+                    │  (Offline HSM)   │
+                    │   95% of funds   │
+                    └────────┬────────┘
+                             │ Manual
+                             │ Transfer
+                    ┌────────▼────────┐
+                    │   Warm Wallet    │
+                    │  (Limited online) │
+                    │   4% of funds    │
+                    └────────┬────────┘
+                             │ Automated
+                             │ Threshold
+                    ┌────────▼────────┐
+                    │    Hot Wallet    │
+                    │  (Always online) │
+                    │   1% of funds    │
+                    └─────────────────┘
+```
+
+### Recommended Security Measures
+
+1. **Multi-signature wallets** for hot wallet (2-of-3 minimum)
+2. **Rate limiting** on withdrawals (per-user and global)
+3. **Withdrawal address whitelisting** with cool-down period
+4. **Monitoring** for unusual patterns
+5. **Key rotation** schedule (quarterly for hot wallet keys)
+6. **Audit logging** of all wallet operations
+
+### Post-Quantum Security
+
+Synor's hybrid signature scheme provides:
+
+- **Current security:** Ed25519 against classical attacks
+- **Future security:** Dilithium3 against quantum attacks
+- **Defense in depth:** Both must be compromised to forge signatures
+
+---
+
+## Test Environment
+
+### Testnet Information
+
+| Property | Value |
+|----------|-------|
+| Network Name | Synor Testnet |
+| Address Prefix | `tsynor1` |
+| RPC Endpoint | `https://testnet-rpc.synor.cc` |
+| WebSocket | `wss://testnet-ws.synor.cc` |
+| Faucet | `https://faucet.synor.cc` |
+| Explorer | `https://testnet.explorer.synor.cc` |
+
+### Getting Test Tokens
+
+```bash
+# Request testnet tokens via faucet API
+curl -X POST https://faucet.synor.cc/request \
+  -H "Content-Type: application/json" \
+  -d '{"address": "tsynor1your_testnet_address..."}'
+```
+
+### Running Local Testnet
+
+```bash
+# Clone repository
+git clone https://github.com/synor/synor.git
+cd synor
+
+# Start local testnet with Docker
+docker compose -f docker-compose.testnet.yml up -d
+
+# Access local RPC
+curl http://localhost:17110 ...
+```
+
+---
+
+## Support
+
+### Integration Support
+
+- **Email:** integration@synor.cc
+- **Telegram:** @SynorExchangeSupport
+- **Documentation:** https://docs.synor.cc/exchange
+
+### API Status
+
+- **Status Page:** https://status.synor.cc
+- **Maintenance Notifications:** Subscribe at status page
+
+---
+
+## Changelog
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0 | 2026-01 | Initial release |
+
+---
+
+*Last updated: January 2026*