Add public Boltz balance endpoint (#125)

* Add public Boltz balance endpoint

- Add GET /v1/boltz-balance endpoint for public wallet balance monitoring
- Create BoltzModule with controller, service, DTOs, entity and repository
- Add asset_boltz table migration with environment-specific token addresses
- Support BTC, Lightning, and EVM token balances (USDC, USDT, WBTC, JUSD, WBTCe)

* Refactor Boltz balance endpoint to return flat array

- Rename endpoint from /boltz-balance to /boltz/balance
- Change response from structured object to flat BalanceDto array
- Rename config key from boltzBalance to boltz
- Update migration to schema-only (remove seed data)
- Add Direction enum for Lightning balance direction

* Rename walletAddress to evmWalletAddress in boltz config

* Changes after review

Author: bernd2022

migration/1770148471000-createAssetBoltz.js

@@ -0,0 +1,28 @@
+/**
+ * @typedef {import('typeorm').MigrationInterface} MigrationInterface
+ * @typedef {import('typeorm').QueryRunner} QueryRunner
+ */
+
+/**
+ * @class
+ * @implements {MigrationInterface}
+ */
+module.exports = class CreateAssetBoltz1770192795341 {
+    name = 'CreateAssetBoltz1770192795341'
+
+    /**
+     * @param {QueryRunner} queryRunner
+     */
+    async up(queryRunner) {
+        await queryRunner.query(`CREATE TABLE "asset_boltz" ("id" int NOT NULL IDENTITY(1,1), "created" datetime2 NOT NULL CONSTRAINT "DF_f8eee661bfc0ba34f0f18960a35" DEFAULT getdate(), "updated" datetime2 NOT NULL CONSTRAINT "DF_bf77b89d4b7d1e854206229afea" DEFAULT getdate(), "name" nvarchar(255) NOT NULL, "blockchain" nvarchar(255) NOT NULL, "address" nvarchar(255) NOT NULL, "decimals" int NOT NULL, CONSTRAINT "PK_ff1e802368b299c2f1a88ec1af6" PRIMARY KEY ("id"))`);
+        await queryRunner.query(`CREATE UNIQUE INDEX "IDX_a5500b6a3fca6dd68cc08ea756" ON "asset_boltz" ("name", "blockchain") `);
+    }
+
+    /**
+     * @param {QueryRunner} queryRunner
+     */
+    async down(queryRunner) {
+        await queryRunner.query(`DROP INDEX "IDX_a5500b6a3fca6dd68cc08ea756" ON "asset_boltz"`);
+        await queryRunner.query(`DROP TABLE "asset_boltz"`);
+    }
+}

src/config/config.ts

@@ -211,6 +211,10 @@ export class Configuration {
     claimApiUrl: process.env.SWAP_CLAIM_API_URL,
   };
 
+  boltz = {
+    evmWalletAddress: process.env.BOLTZ_WALLET_ADDRESS ?? '',
+  };
+
   // --- GETTERS --- //
   get baseUrl(): string {
     return this.environment === Environment.LOC

src/subdomains/alchemy/services/alchemy.service.ts

@@ -15,12 +15,13 @@ export class AlchemyService {
   }
 
   async getTokenBalances(chainId: number, address: string, assets: AssetTransferEntity[]): Promise<TokenBalance[]> {
-    const alchemy = this.getAlchemy(chainId);
-
     const contractAddresses = assets.filter((a) => a.address != null).map((a) => a.address);
+    return this.getTokenBalancesByAddresses(chainId, address, contractAddresses);
+  }
 
-    const tokenBalancesResponse = await alchemy.core.getTokenBalances(address, contractAddresses);
-
+  async getTokenBalancesByAddresses(chainId: number, walletAddress: string, contractAddresses: string[]): Promise<TokenBalance[]> {
+    const alchemy = this.getAlchemy(chainId);
+    const tokenBalancesResponse = await alchemy.core.getTokenBalances(walletAddress, contractAddresses);
     return tokenBalancesResponse.tokenBalances;
   }
 

src/subdomains/boltz/boltz.module.ts

@@ -0,0 +1,16 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { BlockchainModule } from 'src/integration/blockchain/blockchain.module';
+import { AlchemyModule } from '../alchemy/alchemy.module';
+import { BoltzController } from './controllers/boltz.controller';
+import { AssetBoltzEntity } from './entities/asset-boltz.entity';
+import { AssetBoltzRepository } from './repositories/asset-boltz.repository';
+import { BoltzBalanceService } from './services/boltz-balance.service';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([AssetBoltzEntity]), BlockchainModule, AlchemyModule],
+  controllers: [BoltzController],
+  providers: [AssetBoltzRepository, BoltzBalanceService],
+  exports: [],
+})
+export class BoltzModule {}

src/subdomains/boltz/controllers/boltz.controller.ts

@@ -0,0 +1,17 @@
+import { Controller, Get } from '@nestjs/common';
+import { ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { BalanceDto } from '../dto/boltz.dto';
+import { BoltzBalanceService } from '../services/boltz-balance.service';
+
+@ApiTags('Boltz')
+@Controller('boltz')
+export class BoltzController {
+  constructor(private readonly boltzBalanceService: BoltzBalanceService) {}
+
+  @Get('balance')
+  @ApiOperation({ summary: 'Get Boltz wallet balances (public)' })
+  @ApiOkResponse({ type: [BalanceDto] })
+  async getWalletBalance(): Promise<BalanceDto[]> {
+    return this.boltzBalanceService.getWalletBalance();
+  }
+}

src/subdomains/boltz/dto/boltz.dto.ts

@@ -0,0 +1,22 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Blockchain } from 'src/shared/enums/blockchain.enum';
+
+export enum Direction {
+  OUTGOING = 'outgoing',
+  INCOMING = 'incoming'
+}
+
+export class BalanceDto {
+  @ApiProperty({ description: 'Blockchain/Network', enum: Blockchain })
+  blockchain: Blockchain;
+
+  @ApiProperty({ description: 'Asset symbol (e.g. BTC, cBTC, JUSD, USDC, USDT, WBTC)' })
+  asset: string;
+
+  @ApiProperty({ description: 'Balance amount' })
+  balance: number;
+
+  @ApiPropertyOptional({ description: 'Direction (only for Lightning)', required: false, enum: Direction })
+  direction?: Direction;
+}
+

src/subdomains/boltz/entities/asset-boltz.entity.ts

@@ -0,0 +1,19 @@
+import { IEntity } from 'src/shared/db/entity';
+import { Blockchain } from 'src/shared/enums/blockchain.enum';
+import { Column, Entity, Index } from 'typeorm';
+
+@Entity('asset_boltz')
+@Index((asset: AssetBoltzEntity) => [asset.name, asset.blockchain], { unique: true })
+export class AssetBoltzEntity extends IEntity {
+  @Column()
+  name: string;
+
+  @Column()
+  blockchain: Blockchain;
+
+  @Column()
+  address: string;
+
+  @Column({ type: 'int' })
+  decimals: number;
+}

src/subdomains/boltz/repositories/asset-boltz.repository.ts

@@ -0,0 +1,16 @@
+import { Injectable } from '@nestjs/common';
+import { BaseRepository } from 'src/shared/db/base.repository';
+import { Blockchain } from 'src/shared/enums/blockchain.enum';
+import { EntityManager, Equal } from 'typeorm';
+import { AssetBoltzEntity } from '../entities/asset-boltz.entity';
+
+@Injectable()
+export class AssetBoltzRepository extends BaseRepository<AssetBoltzEntity> {
+  constructor(manager: EntityManager) {
+    super(AssetBoltzEntity, manager);
+  }
+
+  async getByBlockchain(blockchain: Blockchain): Promise<AssetBoltzEntity[]> {
+    return this.findBy({ blockchain: Equal(blockchain) });
+  }
+}

src/subdomains/boltz/services/boltz-balance.service.ts

@@ -0,0 +1,206 @@
+import { Injectable, OnModuleInit } from '@nestjs/common';
+import { ethers } from 'ethers';
+import { GetConfig } from 'src/config/config';
+import { BitcoinClient } from 'src/integration/blockchain/bitcoin/bitcoin-client';
+import { BitcoinService } from 'src/integration/blockchain/bitcoin/bitcoin.service';
+import { LightningClient } from 'src/integration/blockchain/lightning/lightning-client';
+import { LightningHelper } from 'src/integration/blockchain/lightning/lightning-helper';
+import { LightningService } from 'src/integration/blockchain/lightning/services/lightning.service';
+import ERC20_ABI from 'src/integration/blockchain/shared/evm/abi/erc20.abi.json';
+import { Blockchain } from 'src/shared/enums/blockchain.enum';
+import { LightningLogger } from 'src/shared/services/lightning-logger';
+import { Util } from 'src/shared/utils/util';
+import { AlchemyNetworkMapper } from 'src/subdomains/alchemy/alchemy-network-mapper';
+import { AlchemyService } from 'src/subdomains/alchemy/services/alchemy.service';
+import { EvmUtil } from 'src/subdomains/evm/evm.util';
+import { BalanceDto, Direction } from '../dto/boltz.dto';
+import { AssetBoltzRepository } from '../repositories/asset-boltz.repository';
+
+interface ChainConfig {
+  blockchain: Blockchain;
+  chainId: number;
+  usesAlchemy: boolean;
+}
+
+@Injectable()
+export class BoltzBalanceService implements OnModuleInit {
+  private readonly logger = new LightningLogger(BoltzBalanceService);
+
+  private readonly bitcoinClient: BitcoinClient;
+  private readonly lightningClient: LightningClient;
+
+  private evmWalletAddress = '';
+  private citreaProvider: ethers.providers.JsonRpcProvider | null = null;
+  private chains: ChainConfig[] = [];
+
+  constructor(
+    bitcoinService: BitcoinService,
+    lightningService: LightningService,
+    private readonly alchemyService: AlchemyService,
+    private readonly assetBoltzRepository: AssetBoltzRepository,
+  ) {
+    this.bitcoinClient = bitcoinService.getDefaultClient();
+    this.lightningClient = lightningService.getDefaultClient();
+  }
+
+  onModuleInit(): void {
+    const config = GetConfig();
+    this.evmWalletAddress = config.boltz.evmWalletAddress;
+    const blockchainConfig = config.blockchain;
+
+    this.chains = [
+      { blockchain: Blockchain.ETHEREUM, chainId: blockchainConfig.ethereum.chainId, usesAlchemy: true },
+      { blockchain: Blockchain.POLYGON, chainId: blockchainConfig.polygon.chainId, usesAlchemy: true },
+      { blockchain: Blockchain.CITREA, chainId: blockchainConfig.citrea.chainId, usesAlchemy: false },
+    ];
+
+    if (blockchainConfig.citrea.gatewayUrl) {
+      this.citreaProvider = new ethers.providers.JsonRpcProvider(blockchainConfig.citrea.gatewayUrl);
+    }
+  }
+
+  async getWalletBalance(): Promise<BalanceDto[]> {
+    const balances: BalanceDto[] = [];
+
+    balances.push(... await this.getBtcBalances());
+    balances.push(... await this.getLightningBalances());
+    balances.push(... await this.getEvmBalances());
+
+    return balances;
+  }
+
+  private async getBtcBalances(): Promise<BalanceDto[]> {
+    const balances: BalanceDto[] = [];
+
+    try {
+      const onchainNode = await this.bitcoinClient.getWalletBalance();
+      balances.push({ blockchain: Blockchain.BITCOIN, asset: 'BTC', balance: LightningHelper.satToBtc(onchainNode) });
+    } catch (error) {
+      this.logger.warn(`Failed to fetch BTC onchain balance: ${error.message}`);
+    }
+
+    try {
+      const lndNode = await this.lightningClient.getLndConfirmedWalletBalance();
+      balances.push({ blockchain: Blockchain.LIGHTNING, asset: 'BTC', balance: LightningHelper.satToBtc(lndNode) });
+    } catch (error) {
+      this.logger.warn(`Failed to fetch LND wallet balance: ${error.message}`);
+    }
+
+    return balances;
+  }
+
+  private async getLightningBalances(): Promise<BalanceDto[]> {
+    const balances: BalanceDto[] = [];
+
+    try {
+      const channels = await this.lightningClient.getChannels();
+      const outgoing = channels.reduce((sum, ch) => sum + Number(ch.local_balance), 0);
+      const incoming = channels.reduce((sum, ch) => sum + Number(ch.remote_balance), 0);
+
+      balances.push({ blockchain: Blockchain.LIGHTNING, asset: 'BTC', balance: LightningHelper.satToBtc(outgoing), direction: Direction.OUTGOING});
+      balances.push({ blockchain: Blockchain.LIGHTNING, asset: 'BTC', balance: LightningHelper.satToBtc(incoming), direction: Direction.INCOMING });
+    } catch (error) {
+      this.logger.warn(`Failed to fetch Lightning balance: ${error.message}`);
+    }
+
+    return balances;
+  }
+
+  private async getEvmBalances(): Promise<BalanceDto[]> {
+    const balances: BalanceDto[] = [];
+
+    // Citrea cBTC (native balance)
+    const citreaBalance = await this.getCitreaNativeBalance();
+    if (citreaBalance) balances.push(citreaBalance);
+
+    // Token balances from all chains
+    for (const chain of this.chains) {
+      try {
+        if (chain.chainId <= 0) continue;
+
+        const tokenBalances = chain.usesAlchemy
+          ? await this.getAlchemyTokenBalances(chain)
+          : await this.getDirectTokenBalances(chain);
+        balances.push(...tokenBalances);
+      } catch (error) {
+        this.logger.warn(`Failed to fetch balances for ${chain.blockchain}: ${error.message}`);
+      }
+    }
+
+    return balances;
+  }
+
+  private async getCitreaNativeBalance(): Promise<BalanceDto | null> {
+    if (!this.citreaProvider || !this.evmWalletAddress) return null;
+
+    try {
+      const balanceWei = await this.citreaProvider.getBalance(this.evmWalletAddress);
+      const balance = EvmUtil.fromWeiAmount(balanceWei.toString());
+
+      return { blockchain: Blockchain.CITREA, asset: 'cBTC', balance };
+    } catch (error) {
+      this.logger.warn(`Failed to fetch Citrea native balance: ${error.message}`);
+      return null;
+    }
+  }
+
+  private async getAlchemyTokenBalances(chain: ChainConfig): Promise<BalanceDto[]> {
+    const balances: BalanceDto[] = [];
+
+    try {
+      if (!AlchemyNetworkMapper.toAlchemyNetworkByChainId(chain.chainId)) return balances;
+
+      if (!this.evmWalletAddress) return balances;
+
+      const tokens = await this.assetBoltzRepository.getByBlockchain(chain.blockchain);
+      if (tokens.length === 0) return balances;
+
+      const tokenAddresses = tokens.map((t) => t.address);
+      const tokenBalances = await this.alchemyService.getTokenBalancesByAddresses(chain.chainId, this.evmWalletAddress, tokenAddresses);
+
+      for (const tokenBalance of tokenBalances) {
+        const token = tokens.find((t) => Util.equalsIgnoreCase(t.address,tokenBalance.contractAddress));
+        if (!token) continue;
+
+        const rawBalance = BigInt(tokenBalance.tokenBalance ?? '0');
+
+        balances.push({
+          blockchain: chain.blockchain,
+          asset: token.name,
+          balance: EvmUtil.fromWeiAmount(rawBalance.toString(), token.decimals),
+        });
+      }
+    } catch (error) {
+      this.logger.warn(`Failed to fetch Alchemy token balances for ${chain.blockchain}: ${error.message}`);
+    }
+
+    return balances;
+  }
+
+  private async getDirectTokenBalances(chain: ChainConfig): Promise<BalanceDto[]> {
+    const balances: BalanceDto[] = [];
+
+    if (!this.citreaProvider || !this.evmWalletAddress) return balances;
+    if (chain.blockchain !== Blockchain.CITREA) return balances;
+
+    const tokens = await this.assetBoltzRepository.getByBlockchain(chain.blockchain);
+    if (tokens.length === 0) return balances;
+
+    for (const token of tokens) {
+      try {
+        const contract = new ethers.Contract(token.address, ERC20_ABI, this.citreaProvider);
+        const rawBalance: ethers.BigNumber = await contract.balanceOf(this.evmWalletAddress);
+
+        balances.push({
+          blockchain: chain.blockchain,
+          asset: token.name,
+          balance: EvmUtil.fromWeiAmount(rawBalance.toString(), token.decimals),
+        });
+      } catch (error) {
+        this.logger.warn(`Failed to fetch ${token.name} balance on ${chain.blockchain}: ${error.message}`);
+      }
+    }
+
+    return balances;
+  }
+}

src/subdomains/user/user.module.ts

@@ -4,6 +4,7 @@ import { LnbitsWebhookModule } from 'src/integration/blockchain/lightning/lnbits
 import { IntegrationModule } from 'src/integration/integration.module';
 import { SharedModule } from 'src/shared/shared.module';
 import { AuthService } from 'src/subdomains/user/application/services/auth.service';
+import { BoltzModule } from '../boltz/boltz.module';
 import { LightningTransactionModule } from '../lightning/lightning-transaction.module';
 import { AssetModule } from '../master-data/asset/asset.module';
 import { MonitoringModule } from '../monitoring/monitoring.module';
@@ -43,6 +44,7 @@ import { WalletEntity } from './domain/entities/wallet.entity';
     SharedModule,
     IntegrationModule,
     MonitoringModule,
+    BoltzModule,
     AssetModule,
     LnbitsWebhookModule,
     LightningTransactionModule,