From 960c25eb8a417bb8dd3323b8d17291f7d03752ae Mon Sep 17 00:00:00 2001 From: Gulshan Yadav Date: Sat, 10 Jan 2026 06:20:35 +0530 Subject: [PATCH] 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 --- docs/EXCHANGE_INTEGRATION.md | 532 +++++++++++++++++++++++++++++++++++ 1 file changed, 532 insertions(+) create mode 100644 docs/EXCHANGE_INTEGRATION.md diff --git a/docs/EXCHANGE_INTEGRATION.md b/docs/EXCHANGE_INTEGRATION.md new file mode 100644 index 0000000..c991f76 --- /dev/null +++ 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*