Skip to content

Latest commit

 

History

History
350 lines (267 loc) · 9.69 KB

README.md

File metadata and controls

350 lines (267 loc) · 9.69 KB
Raw

optibridge

License TypeScript Redis Bun

Table of Contents

Introduction

Welcome to the optibridge project! This backend service is designed to facilitate optimal cross-chain token bridging by calculating the most efficient routes based on user requests. Leveraging multiple blockchain networks, the service ensures minimal fees and optimal transaction times, providing a seamless bridging experience for users.

Features

  • Optimal Route Calculation: Determines the best possible paths for token bridging across supported blockchain networks.
  • Dynamic Fee Management: Integrates with external APIs to fetch real-time bridge fees and applies fallback mechanisms when necessary.
  • Caching with Redis: Implements caching strategies to enhance performance and reduce redundant API calls.
  • Robust Error Handling: Comprehensive error management to handle various failure scenarios gracefully.
  • Test Mode: Allows simulation of different blockchain balances for testing purposes without interacting with actual networks.
  • Scalable Architecture: Built with scalability in mind, accommodating the addition of more blockchain networks with ease.

Technology Stack

Getting Started

Prerequisites

Ensure you have the following installed on your system:

Installation

  1. Clone the Repository

    git clone https://github.com/takshakmudgal/optibridge.git
cd optibridge

  2. Install Dependencies

    Using Bun:

    bun install

Configuration

  1. Environment Variables

    Create a .env file in the root directory and populate it with the required environment variables:

    SOCKET_API_KEY=your_socket_api_key
REDIS_URL=redis://localhost:6379
PORT=3000
    • SOCKET_API_KEY: Your API key for the Socket API service.
    • REDIS_URL: Connection URL for your Redis instance.
    • PORT: Port on which the application will run (default is 3000).

  2. Supported Chains Configuration

    The application supports multiple blockchain networks. You can configure supported chains in the src/config/chains.ts file. Each chain configuration includes:

    • name: Human-readable name of the chain.
    • chainId: Unique identifier for the blockchain.
    • nativeToken: The native cryptocurrency of the chain.
    • usdcAddress: Contract address for USDC on the chain.
    • rpcUrl: RPC endpoint for interacting with the blockchain.

  3. Bridge Fees Configuration

    Bridge fees between chains are defined in src/config/bridgeFees.ts. You can adjust the fees as needed:

    export const BRIDGE_FEES: Record<string, Record<string, number>> = {
  arbitrum: {
    polygon: 1,
  },
  base: {
    polygon: 0.5,
  },
  gnosis: {
    polygon: 0.1,
  },
  blast: {
    polygon: 0.2,
  },
};

Usage

Running the Application

Start the development server using Bun:

bun run dev

The server will start on the specified port (default: 3000). You should see a console message indicating that Elysia is running:

🦊 Elysia is running at localhost:3000

API Endpoints

POST /api/bridge/routes

Calculates the optimal bridging routes based on the user's request.

  • Request Body

    {
  "targetChain": "string",      // The blockchain network to bridge to (e.g., "polygon")
  "amount": number,             // The amount of tokens to bridge
  "tokenAddress": "string",     // The contract address of the token to bridge
  "userAddress": "string"       // The user's wallet address initiating the bridge
}
    • Validation Rules:
      • targetChain: Must be a supported chain.
      • amount: Must be a positive number.
      • tokenAddress & userAddress: Must be valid Ethereum addresses (42 characters, starting with 0x).

  • Response

    • Success

      {
  "success": true,
  "data": {
    "routes": [
      {
        "sourceChain": "string",
        "amount": number,
        "fee": number,
        "estimatedTime": number,
        "protocol": "string",
        "gasToken": "string",
        "sourceBalance": number
      }
    ],
    "totalFee": number,
    "totalAmount": number,
    "estimatedTotalTime": number,
    "availableBalance": number,
    "requiredAmount": number,
    "insufficientFunds": false,
    "noValidRoutes": false,
    "bridgeRoutes": [
      {
        "sourceChain": "string",
        "amount": number,
        "fee": number,
        "estimatedTime": number,
        "protocol": "string",
        "gasToken": "string"
      }
    ],
    "targetChain": "string",
    "shortfall": number
  },
  "error": null
}

    • Failure

      {
  "success": false,
  "error": "Error message detailing the issue",
  "data": {
    "routes": [],
    "totalFee": 0,
    "totalAmount": 0,
    "estimatedTotalTime": 0,
    "availableBalance": 0,
    "requiredAmount": number,
    "insufficientFunds": true,
    "noValidRoutes": true,
    "bridgeRoutes": [],
    "targetChain": "string",
    "shortfall": number
  }
}

  • Example Request

    curl -X POST http://localhost:3000/api/bridge/routes \
  -H "Content-Type: application/json" \
  -d '{
        "targetChain": "arbitrum",
        "amount": 100,
        "tokenAddress": "0xFF970A61A04b1cA14834A43f5dE4533eBDDB5CC8",
        "userAddress": "0xYourEthereumAddressHere"
      }'

Project Structure

optibridge/
├── src/
│   ├── config/
│   │   ├── bridgeFees.ts
│   │   ├── chains.ts
│   │   ├── env.ts
│   │   └── redis.ts
│   ├── controllers/
│   │   └── bridgeController.ts
│   ├── services/
│   │   ├── routeCalculator.ts
│   │   └── socketApi.ts
│   ├── types/
│   │   ├── index.ts
│   │   └── socket.ts
│   ├── utils/
│   │   ├── errors.ts
│   │   └── validation.ts
│   └── server.ts
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md
  • src/config/: Contains configuration files for environment variables, Redis, supported chains, and bridge fees.
  • src/controllers/: Handles incoming API requests and orchestrates responses.
  • src/services/: Contains business logic for route calculation and external API interactions.
  • src/types/: Defines TypeScript interfaces and types used throughout the application.
  • src/utils/: Utility functions and custom error classes.
  • src/server.ts: Entry point of the application, sets up the Elysia server and routes.

Contributing

Contributions are welcome! Please follow these steps to contribute:

  1. Fork the Repository

  2. Create a Feature Branch

    git checkout -b feature/YourFeatureName

  3. Commit Your Changes

    git commit -m "Add your message here"

  4. Push to the Branch

    git push origin feature/YourFeatureName

  5. Open a Pull Request

Please ensure your code adheres to the project's coding standards and passes all existing tests.

Running with Docker

To run optibridge using Docker, follow these steps:

Prerequisites

Steps

  1. Clone the Repository

    git clone https://github.com/takshakmudgal/optibridge.git
cd optibridge

  2. Create a .env File

    Create a .env file in the root directory and add your environment variables:

    SOCKET_API_KEY=your_socket_api_key
PORT=3000

  3. Build and Run with Docker Compose

    docker-compose up --build

    This command will build the Docker image and start both the application and Redis services. The application will be accessible at http://localhost:3000.

  4. Stopping the Services

    To stop the services, press Ctrl + C in the terminal where Docker Compose is running, then execute:

    docker-compose down

Notes

  • The application code is mounted into the Docker container, allowing for live-reloading during development.
  • Redis data is persisted using Docker volumes to prevent data loss between restarts.

License

This project is licensed under the MIT License. See the LICENSE file for details.