smom-dbis-138/docs/bridge/DEPLOYMENT_GUIDE.md

# Bridge Deployment Guide

## Prerequisites

1. **Chain 138 Node**: Running and accessible via RPC
2. **Deployer Account**: Funded with native tokens for gas
3. **HSM Service**: Configured and accessible (for production)
4. **FireFly Instance**: Deployed and configured
5. **Cacti Connectors**: XRPL and EVM connectors configured

## Environment Variables

Create a `.env` file with the following variables:

```bash
# Chain 138 Configuration
CHAIN_138_RPC_URL=http://localhost:8545
DEPLOYER_PRIVATE_KEY=0x...
ADMIN_ADDRESS=0x...
HSM_SIGNER_ADDRESS=0x...

# thirdweb Configuration
THIRDWEB_CLIENT_ID=your-client-id

# XRPL Configuration
XRPL_SERVER=wss://s1.ripple.com
XRPL_ACCOUNT=r...
XRPL_SECRET=s...

# FireFly Configuration
FIREFLY_API_URL=http://localhost:5000
FIREFLY_API_KEY=your-api-key

# Cacti Configuration
CACTI_API_URL=http://localhost:4000

# HSM Configuration
HSM_ENDPOINT=http://localhost:8080
HSM_API_KEY=your-hsm-api-key
HSM_KEY_ID=your-key-id
```

## Deployment Steps

### 1. Deploy Smart Contracts

```bash
cd smom-dbis-138
chmod +x scripts/deployment/deploy-bridge-contracts.sh
./scripts/deployment/deploy-bridge-contracts.sh
```

This will deploy:
- BridgeRegistry
- BridgeEscrowVault
- wXRP Token
- MintBurnController
- BridgeVerifier

### 2. Initialize Registry

After deployment, initialize the registry with destinations and tokens:

```bash
forge script script/bridge/interop/InitializeRegistry.s.sol \
    --rpc-url $CHAIN_138_RPC_URL \
    --private-key $DEPLOYER_PRIVATE_KEY \
    --broadcast
```

### 3. Configure FireFly

Update FireFly configuration to use the deployed contracts:

```yaml
# firefly-config.yaml
blockchain:
  rpc: ${CHAIN_138_RPC_URL}
  chainId: 138
  contracts:
    escrowVault: ${BRIDGE_ESCROW_VAULT_ADDRESS}
    registry: ${BRIDGE_REGISTRY_ADDRESS}
```

### 4. Configure Cacti Connectors

#### XRPL Connector

```bash
curl -X POST ${CACTI_API_URL}/api/v1/plugins/ledger-connector/xrpl \
  -H "Content-Type: application/json" \
  -d '{
    "ledgerId": "xrpl-mainnet",
    "server": "${XRPL_SERVER}",
    "account": "${XRPL_ACCOUNT}"
  }'
```

#### EVM Connector (Chain 138)

```bash
curl -X POST ${CACTI_API_URL}/api/v1/plugins/ledger-connector/besu \
  -H "Content-Type: application/json" \
  -d '{
    "ledgerId": "chain-138",
    "chainId": 138,
    "rpc": {
      "http": "${CHAIN_138_RPC_URL}",
      "ws": "${CHAIN_138_WS_URL}"
    }
  }'
```

### 5. Deploy Frontend

```bash
cd frontend-dapp
npm install
npm run build

# Set environment variables
export VITE_THIRDWEB_CLIENT_ID=your-client-id
export VITE_API_URL=https://api.bridge.chain138.example.com

# Deploy to your hosting service
npm run deploy
```

### 6. Set Up Monitoring

#### Prometheus

```bash
# Copy prometheus config
cp monitoring/prometheus/bridge-metrics.yml /etc/prometheus/bridge-metrics.yml

# Reload Prometheus
systemctl reload prometheus
```

#### Grafana

1. Import dashboard from `monitoring/grafana/bridge-dashboard.json`
2. Configure data source to point to Prometheus
3. Set up alerting rules

### 7. Configure HSM

For production, configure HSM signing:

```bash
# Test HSM connection
curl -X GET ${HSM_ENDPOINT}/health \
  -H "Authorization: Bearer ${HSM_API_KEY}"

# Register HSM signer address in contracts
forge script script/bridge/interop/SetHSMSigner.s.sol \
    --rpc-url $CHAIN_138_RPC_URL \
    --private-key $DEPLOYER_PRIVATE_KEY \
    --broadcast \
    --sig "run(address,address)" $MINT_BURN_CONTROLLER_ADDRESS $HSM_SIGNER_ADDRESS
```

## Verification

### 1. Verify Contracts

```bash
# Verify on explorer
forge verify-contract \
    --chain-id 138 \
    --num-of-optimizations 200 \
    --watch \
    --constructor-args $(cast abi-encode "constructor(address)" $ADMIN_ADDRESS) \
    $BRIDGE_REGISTRY_ADDRESS \
    BridgeRegistry
```

### 2. Test Bridge Operations

```bash
# Test native ETH deposit
cast send $BRIDGE_ESCROW_VAULT_ADDRESS \
    "depositNative(uint8,bytes,uint256,bytes32)" \
    0 \
    $(cast --to-bytes32 0x100) \
    3600 \
    $(cast --to-bytes32 0x123) \
    --value 1ether \
    --rpc-url $CHAIN_138_RPC_URL \
    --private-key $TEST_PRIVATE_KEY
```

### 3. Check Metrics

```bash
# Check Prometheus metrics
curl http://localhost:9090/api/v1/query?query=bridge_total_transfers
```

## Post-Deployment

### 1. Set Up Attestors

Add attestors to BridgeVerifier:

```bash
forge script script/bridge/interop/AddAttestor.s.sol \
    --rpc-url $CHAIN_138_RPC_URL \
    --private-key $DEPLOYER_PRIVATE_KEY \
    --broadcast \
    --sig "run(address,address,uint256)" \
    $BRIDGE_VERIFIER_ADDRESS \
    $ATTESTOR_ADDRESS \
    1000
```

### 2. Configure Token Allowlist

Add tokens to registry:

```bash
forge script script/bridge/interop/RegisterToken.s.sol \
    --rpc-url $CHAIN_138_RPC_URL \
    --private-key $DEPLOYER_PRIVATE_KEY \
    --broadcast \
    --sig "run(address,address,uint256,uint256,uint256[],uint8,uint256)" \
    $BRIDGE_REGISTRY_ADDRESS \
    $TOKEN_ADDRESS \
    1000000000000000 \
    100000000000000000000 \
    "[137,10,8453]" \
    0 \
    5
```

### 3. Set Up Alerts

Configure alerting in Grafana or Prometheus Alertmanager for:
- High failure rates
- Low success rates
- High settlement times
- Liquidity failures
- Bridge pause events

## Troubleshooting

### Contract Deployment Fails

- Check RPC connection: `cast block-number --rpc-url $CHAIN_138_RPC_URL`
- Verify deployer has sufficient balance
- Check gas price settings

### FireFly Connection Issues

- Verify FireFly can connect to Chain 138 RPC
- Check FireFly logs: `kubectl logs -f firefly-core`
- Verify contract addresses in FireFly config

### XRPL Connection Issues

- Test XRPL connection: `xrpl-cli ping`
- Verify XRPL account has sufficient balance
- Check XRPL server accessibility

### HSM Signing Issues

- Test HSM health endpoint
- Verify HSM API key is correct
- Check HSM key ID exists
- Review HSM logs for errors

## Rollback Procedure

If deployment fails:

1. **Pause Bridge**: Call `pause()` on all contracts
2. **Review Logs**: Check deployment logs for errors
3. **Fix Issues**: Address identified problems
4. **Redeploy**: Run deployment script again
5. **Verify**: Test all operations before resuming

## Support

For deployment support:
- Check logs: `logs/bridge-deployment.log`
- Review documentation: `docs/bridge/`
- Contact: devops@chain138.example.com