README.md

Carbon Backend

Carbon Backend, built with Nest.js, serves as a specialized backend solution for aggregating insights from Carbon smart contracts and delivering them through APIs. It provides a suite of APIs offering valuable insights, such as trading activity and history.

Prerequisites

Before setting up Carbon Backend, ensure you have the following prerequisites:

• TimescaleDB: Ensure TimescaleDB is properly installed and running.
• Redis: Ensure Redis is properly installed and running.
• CoinGecko: Obtain an API key from CoinGecko.
• CoinMarketCap: Obtain an API key from CoinMarketCap.
• Python 3 (Optional): Required for the simulator.

Installation

To set up Carbon Backend, follow these steps:

1. Clone the repository:

   git clone https://github.com/bancorprotocol/carbon-backend

2. Navigate to the project directory:

   cd carbon-backend

3. Install dependencies:

   npm install

4. Run database migrations:

   After installing dependencies, run the following command to execute all migrations and prepare the database:

   npm run migration:run

5. Configure environment variables:

   Duplicate the .env.example file as .env:

   cp .env.example .env

   Provide the required values in the .env file.

6. (Optional) If you wish to utilize the simulator feature, install the required Python packages:

   pip install -r src/simulator/requirements.txt

Usage

To run Carbon Backend:

npm start

API Documentation

Access the API documentation by navigating to http://localhost:3000 in your browser.

Seed Historic Quotes (Optional)

Manually run the seed function in src/historic-quote/historic-quote.service.ts to populate the database with historic quotes for history-dependent functionalities such as the simulator.

Change Network

To switch Carbon Backend's network for different deployments, follow these steps:

1. Replace Smart Contract Files:

   • Replace files in src/contracts/mainnet with those from the new deployment.

2. Modify CoinMarketCap Service:

   • Adjust src/coinmarketcap/coinmarketcap.service.ts to align with the new network.
   • For guidance, check the CoinMarketCap API documentation.

3. Modify CoinGecko Service:

   • Adjust src/quote/coingecko.service.ts to match the requirements of the new network.
   • Refer to the CoinGecko API documentation for assistance.

4. Customizing Networks and Exchange IDs:

   To configure which networks are supported by Carbon Backend, make the following changes in deployment.service.ts and exchange-id-param.decorator.ts.

   Supporting Multiple Networks

   If you want to support multiple networks, update the following:

   • In deployment.service.ts:

     • Update the BlockchainType and ExchangeId enums to reflect the networks you want to support:

       export enum BlockchainType {
         Ethereum = 'ethereum',
         Sei = 'sei-network',
         Celo = 'celo',
         Blast = 'blast',
         // Add or remove entries as needed
       }
       
       export enum ExchangeId {
         OGEthereum = 'ethereum',
         OGSei = 'sei',
         OGCelo = 'celo',
         OGBlast = 'blast',
         // Add or remove entries as needed
       }

     • Modify initializeDeployments with configuration for each network, including exchangeId, blockchainType, rpcEndpoint, and other network-specific values:

       private initializeDeployments(): Deployment[] {
         return [
           {
             exchangeId: ExchangeId.OGEthereum,
             blockchainType: BlockchainType.Ethereum,
             rpcEndpoint: this.configService.get('ETHEREUM_RPC_ENDPOINT'),
             harvestEventsBatchSize: 2000000,
             harvestConcurrency: 10,
             multicallAddress: '0x5Eb3fa2DFECdDe21C950813C665E9364fa609bD2',
             startBlock: 17087000,
             gasToken: {
               name: 'Ethereum',
               symbol: 'ETH',
               address: NATIVE_TOKEN,
             },
           },
           // Repeat this block for each network
         ];
       }

   • In exchange-id-param.decorator.ts:

     • Adjust extractExchangeId to support dynamic handling for multiple networks:

       export function extractExchangeId(request: Request, exchangeIdParam?: string): ExchangeId {
         let exchangeId: ExchangeId;
       
         if (exchangeIdParam) {
           exchangeId = exchangeIdParam as ExchangeId;
         } else {
           let subdomain = request.hostname.split('.')[0];
           if (subdomain.endsWith('-api')) {
             subdomain = subdomain.slice(0, -4); // Remove '-api' suffix
           }
           if (subdomain === 'api') {
             subdomain = ExchangeId.OGEthereum; // Adjust to your preferred default network
           }
           exchangeId = subdomain ? (subdomain as ExchangeId) : (ExchangeId.OGEthereum as ExchangeId);
         }
       
         if (!Object.values(ExchangeId).includes(exchangeId)) {
           throw new Error(`Invalid ExchangeId: ${exchangeId}`);
         }
       
         return exchangeId;
       }

   Supporting a Single Network

   If supporting only one network, simplify the configuration:

   • In deployment.service.ts:

     • Set a single BlockchainType and ExchangeId, and configure initializeDeployments for only that network.

   • In exchange-id-param.decorator.ts:

     • Hardcode the extractExchangeId function to return only the supported ExchangeId:

       export function extractExchangeId(request: Request, exchangeIdParam?: string): ExchangeId {
         const exchangeId = ExchangeId.OGEthereum; // Replace with the single supported ExchangeId
       
         if (exchangeIdParam && exchangeIdParam !== exchangeId) {
           throw new Error(`Unsupported ExchangeId: only ${exchangeId} is allowed`);
         }
       
         return exchangeId;
       }

License

Carbon Backend is licensed under the MIT License.