Skip to main content

​
Overview

This quickstart guide will help you set up the deBridge contracts, run tests, and execute your first cross-chain transfer. By the end, you’ll understand the basic workflow of the protocol.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 16.x or higher
  • Yarn or npm package manager
  • Git for cloning the repository

​
Installation

1

Clone the Repository

Clone the deBridge contracts repository:
git clone https://github.com/debridge-finance/debridge-contracts-v1.git
cd debridge-contracts-v1
2

Install Dependencies

Install all required packages:
npm install
3

Compile Contracts

Compile the smart contracts:
yarn compile
This generates:
  • Compiled bytecode in artifacts/
  • TypeChain type definitions
  • Contract ABIs

​
Running Tests

Verify your setup by running the test suite: 
yarn test
Expected output: 
DeBridgePipeline
  ✓ Should send native asset (432ms)
  ✓ Should send ERC20 token (523ms)
  ✓ Should claim transfer (891ms)
  ...

85 passing (2m 14s)
If you encounter module errors, run yarn hardhat clean and then yarn compile again.

​
Understanding the Architecture

The deBridge Protocol consists of several key components:

DeBridgeGate

Main contract for sending assets and messages cross-chain

CallProxy

Executes cross-chain smart contract calls

OraclesManager

Manages the decentralized validator network

DeBridgeToken

ERC-20 wrapped tokens for cross-chain assets

​
Your First Cross-Chain Transfer

Let’s walk through sending assets cross-chain:
1

Set Up Environment

Create a .env file with your configuration:
.env
# Network RPC URLs
MAINNET_RPC_URL=https://eth-mainnet.alchemyapi.io/v2/YOUR-API-KEY
BSC_RPC_URL=https://bsc-dataseed.binance.org/

# For testnet deployment
DEPLOYER_PRIVATE_KEY=0x...

# Oracle keys (for testing)
TEST_ORACLE_KEYS=["0x512aba...","0x79b2a2..."]
Never commit your .env file or expose private keys.
2

Connect to DeBridgeGate

In your application code:
Connect to Contract
import { ethers } from 'ethers';
import { DeBridgeGate__factory } from './typechain-types';

const provider = new ethers.providers.JsonRpcProvider(RPC_URL);
const wallet = new ethers.Wallet(PRIVATE_KEY, provider);

const debridgeGate = DeBridgeGate__factory.connect(
    DEBRIDGEGATE_ADDRESS,
    wallet
);
3

Send Native Tokens

Send ETH to another chain:
Send ETH Cross-Chain
const amount = ethers.utils.parseEther('0.1'); // 0.1 ETH
const chainIdTo = 56; // BSC
const receiverAddress = '0x...'; // Recipient on BSC

// Get protocol fee
const protocolFee = await debridgeGate.globalFixedNativeFee();

// Send transaction
const tx = await debridgeGate.send(
    ethers.constants.AddressZero,           // Native token
    amount,
    chainIdTo,
    ethers.utils.hexZeroPad(receiverAddress, 32),
    '0x',                                    // No permit
    false,                                   // Pay fee separately
    0,                                       // No referral
    '0x',                                    // No auto params
    { value: amount.add(protocolFee) }
);

console.log('Transaction:', tx.hash);
const receipt = await tx.wait();

// Get submission ID from event
const sentEvent = receipt.events?.find(e => e.event === 'Sent');
console.log('Submission ID:', sentEvent?.args?.submissionId);
4

Track Transaction

Monitor your cross-chain transaction:Enter your transaction hash or submission ID to see the status.

​
Running Examples

The repository includes working examples:

​
Send Native Token

yarn ts-node examples/src/sendScripts/sendETH.ts

​
Send ERC-20 Token

yarn ts-node examples/src/sendScripts/sendERC20.ts

​
Cross-Chain Message (Incrementor)

# Deploy on both chains
yarn hardhat run --network bsctest examples/src/incrementorScripts/deploy.ts
yarn hardhat run --network kovan examples/src/incrementorScripts/deploy.ts

# Configure contracts
yarn hardhat run --network bsctest examples/src/incrementorScripts/setContractAddressOnChainId.ts
yarn hardhat run --network kovan examples/src/incrementorScripts/addControllingAddress.ts

# Send message
yarn hardhat run --network bsctest examples/src/incrementorScripts/send.ts
See the Examples section for detailed guides on each example.

​
Key Concepts

Before building with deBridge, understand these core concepts:
  1. Lock-and-Mint: Assets are locked on the source chain and wrapped tokens (deTokens) are minted on the destination
  2. Oracle Network: Independent validators sign and verify cross-chain transactions
  3. CallProxy: Enables arbitrary smart contract calls across chains
  4. Fees: Consist of fixed protocol fees and percentage-based transfer fees
Learn more in the Core Concepts section.

​
Next Steps

Architecture Overview

Understand how the protocol works

Integration Guide

Integrate deBridge into your application

Smart Contracts

Explore contract documentation

Examples

Learn from working examples

​
Common Issues

TypeChain types haven’t been generated yet.Solution:
yarn hardhat clean
yarn compile
The bridge doesn’t have enough liquidity for your transfer.Solution:
  • Check maxAmount for the asset
  • Try a smaller amount
  • Wait for liquidity to be replenished
Insufficient execution fee was provided.Solution:
  • Include a higher execution fee when sending
  • Manually claim the transaction (advanced)

​
Resources

​
Support

Need help? Reach out through:
  • Discord: Join the #developer channel
  • GitHub Issues: Report bugs or request features
  • Documentation: Check the integration guides
Start with testnet deployments before moving to mainnet. Test thoroughly with small amounts first.

Build docs developers (and LLMs) love

Get started for freeTalk to us