XDC Bridge Specification

1. Executive Summary

The XDC Network is an enterprise-grade, EVM-compatible blockchain designed for trade finance and tokenized real-world assets. Its native support for ISO 20022 messaging standards (via the Impel protocol) makes it a natural counterpart for JIL Sovereign's institutional settlement infrastructure. With approximately 2-second block times, deterministic finality in under 6 seconds, and a thriving ecosystem of tokenized trade instruments, XDC represents one of the highest-value cross-chain integration targets in the institutional DeFi space.

This specification defines the JIL-XDC Bridge: a lock-and-mint bridge secured by JIL's 14-of-20 decentralized validator set, enabling bidirectional transfer of assets between the JIL L1 ledger and the XDC Network. Because XDC is fully EVM-compatible (Solidity 0.8.24), JIL leverages its existing JILBridge.sol contract suite with zero code changes, deploying the same battle-tested contracts already validated on Ethereum and Sepolia.

2. XDC Network Overview

XDC Network (formerly XinFin) is a delegated proof-of-stake blockchain optimized for international trade and finance. It provides the throughput and finality characteristics required for institutional settlement while maintaining full compatibility with the Ethereum toolchain.

3. Architecture

The JIL-XDC Bridge follows a lock-and-mint model secured by JIL's decentralized validator set. Assets deposited on one chain are locked in the bridge contract, and corresponding wrapped assets are minted on the destination chain. Withdrawals reverse this process: wrapped assets are burned and original assets are released after validator approval.

  ┌─────────────┐         ┌──────────────────┐         ┌─────────────┐
  │   JIL L1    │ <─────> │  Bridge Relayer   │ <─────> │ XDC Network │
  │   Ledger    │         │  (lock-and-mint)  │         │  (Chain 50) │
  └─────────────┘         └──────────────────┘         └─────────────┘
        │                         │                          │
   JILBridge.sol            14-of-20 Validator          JILBridge.sol
   JILWrappedERC20          Consensus Layer             JILWrappedERC20
   ComplianceHook           Merkle Proof Relay          ComplianceHook

3.1 Bridge Flows

Deposit Flow (XDC to JIL):

1. User calls deposit() on JILBridge.sol deployed on XDC
2. XRC-20 tokens or native XDC are locked in the bridge contract
3. Bridge relayer detects the deposit event on XDC
4. Relayer submits Merkle proof to JIL L1 validators
5. 14-of-20 validators approve the mint
6. Wrapped tokens (wXDC, wJIL) are minted on JIL L1

Withdrawal Flow (JIL to XDC):

1. User calls burn() on JIL L1 to destroy wrapped tokens
2. Burn event is recorded on JIL L1 ledger
3. Bridge relayer generates burn proof
4. 14-of-20 validators sign the withdrawal approval
5. Challenge period elapses (24h for amounts >$100K)
6. Relayer calls release() on XDC to unlock original assets

3.2 Relayer Architecture

The bridge relayer is a stateless service that monitors events on both chains. It does not hold custody of any assets. Its role is strictly limited to relaying proofs between chains and submitting validator-signed transactions. The relayer runs as a redundant cluster with at least 3 instances for fault tolerance.

4. Smart Contracts

The JIL-XDC bridge reuses the same audited contract suite deployed on Ethereum. Because XDC is fully EVM-compatible, the contracts compile and deploy with identical bytecode.

4.1 Contract Interfaces

// JILBridge.sol - Core deposit and withdrawal interface
interface IJILBridge {
    function deposit(address token, uint256 amount, bytes32 destChainId) external payable;
    function release(address token, address to, uint256 amount, bytes32[] calldata proof) external;
    function setValidatorThreshold(uint8 threshold) external; // governance only
    function pause() external; // emergency governance action
}

// JILWrappedERC20.sol - Wrapped token interface
interface IJILWrappedERC20 {
    function mint(address to, uint256 amount) external; // bridge only
    function burn(address from, uint256 amount) external; // bridge only
    function setComplianceHook(address hook) external; // governance only
}

// DefaultComplianceHook.sol - Compliance checks on transfer
interface IComplianceHook {
    function beforeTransfer(address from, address to, uint256 amount) external view returns (bool);
    function addToBlocklist(address account) external; // compliance officer
    function setLargeWithdrawalThreshold(uint256 amount) external; // governance
}

5. Supported Assets

The JIL-XDC bridge supports bidirectional transfer of the following asset types at launch. Additional XRC-20 tokens can be whitelisted through governance proposals.

6. Security Model

The JIL-XDC Bridge inherits the full security model of JIL Sovereign's decentralized validator infrastructure. Every cross-chain operation requires cryptographic approval from a supermajority of validators distributed across 13 jurisdictions.

6.1 Challenge Period

After a withdrawal is approved by the validator set, a challenge period begins before finalization. During this window, any validator can submit a fraud proof to halt the withdrawal. Standard withdrawals (under $100K) have a 1-hour challenge period. Large withdrawals (over $100K) have a 24-hour challenge period.

6.2 Emergency Controls

The bridge contract includes a pause() function callable only by a governance multi-sig (5-of-9 core team members). When paused, no new deposits or withdrawals can be initiated, but in-flight operations continue to settle. Unpausing requires a governance vote with 14-of-20 validator approval.

7. Address Normalization

XDC Network uses a non-standard address format with an xdc prefix instead of the Ethereum-standard 0x prefix. While both formats refer to the same underlying 20-byte address, tooling and user interfaces must handle the conversion correctly.

7.1 Format Conversion

7.2 Bridge Relayer Normalization

The bridge relayer automatically normalizes addresses between the two formats. When a user submits a deposit with an xdc-prefixed address, the relayer converts it to 0x format before passing it to the smart contract layer. When displaying addresses to users, the relayer converts back to xdc format for XDC-side transactions.

// Address normalization utility
function normalizeXdcAddress(address: string): string {
  if (address.toLowerCase().startsWith('xdc')) {
    return '0x' + address.slice(3);
  }
  return address;
}

function toXdcFormat(address: string): string {
  if (address.toLowerCase().startsWith('0x')) {
    return 'xdc' + address.slice(2);
  }
  return address;
}

8. Configuration

The bridge deployment requires the following environment variables and Hardhat network configuration. All sensitive values (deployer keys, validator keys) must be stored in a secure vault and injected at deploy time.

8.1 Environment Variables

8.2 Hardhat Network Configuration

// hardhat.config.ts - XDC network configuration
const config: HardhatUserConfig = {
  networks: {
    xdc: {
      url: process.env.XDC_RPC_URL || "https://rpc.xdc.org",
      chainId: 50,
      accounts: [process.env.DEPLOYER_KEY],
      gasPrice: 250_000_000, // 0.25 Gwei (XDC gas is very cheap)
    },
    apothem: {
      url: process.env.XDC_APOTHEM_RPC_URL || "https://rpc.apothem.network",
      chainId: 51,
      accounts: [process.env.DEPLOYER_KEY],
      gasPrice: 250_000_000,
    },
  },
  solidity: {
    version: "0.8.24",
    settings: {
      optimizer: { enabled: true, runs: 200 },
    },
  },
};

9. Deployment

Bridge deployment uses the deploy-xdc.ts Hardhat script, which handles contract deployment, validator registration, and compliance hook configuration in a single atomic sequence.

9.1 Apothem Testnet Deployment

# 1. Install dependencies
npm install

# 2. Compile contracts
npx hardhat compile

# 3. Deploy to Apothem testnet
npx hardhat run scripts/deploy-xdc.ts --network apothem

# 4. Verify contracts on Apothem explorer
npx hardhat verify --network apothem <BRIDGE_ADDRESS>
npx hardhat verify --network apothem <WRAPPED_TOKEN_ADDRESS>
npx hardhat verify --network apothem <COMPLIANCE_HOOK_ADDRESS>

9.2 XDC Mainnet Deployment

# 1. Ensure deployer wallet has sufficient XDC for gas
# Estimated: ~5 XDC for full deployment (bridge + wrapped token + compliance hook)

# 2. Deploy to XDC Mainnet
npx hardhat run scripts/deploy-xdc.ts --network xdc

# 3. Verify contracts on XDC BlocksScan
npx hardhat verify --network xdc <BRIDGE_ADDRESS>
npx hardhat verify --network xdc <WRAPPED_TOKEN_ADDRESS>
npx hardhat verify --network xdc <COMPLIANCE_HOOK_ADDRESS>

# 4. Register validators (14-of-20 threshold)
npx hardhat run scripts/register-validators.ts --network xdc

# 5. Configure compliance hook parameters
npx hardhat run scripts/configure-compliance.ts --network xdc

9.3 Post-Deployment Verification

• Confirm bridge contract is deployed and unpaused on XDC BlocksScan
• Verify all 20 validator addresses are registered in the bridge contract
• Test a small deposit/withdrawal cycle on Apothem before mainnet
• Confirm compliance hook is correctly linked to the wrapped token
• Verify address normalization works for both xdc and 0x formats
• Run the bridge relayer health check: curl http://relayer:8080/health
• Monitor first 100 mainnet transactions for anomalies before full launch