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:

# 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

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:

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:

# 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

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)

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

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

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

# 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

# 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

# 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

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

Post-Deployment

1. Set Up Attestors

Add attestors to BridgeVerifier:

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:

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