synor/docs/EXCHANGE_INTEGRATION.md

# 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*