@gibs/bridge-sdk 1.7.1 → 1.7.3

package/README.md

@@ -1,23 +1,487 @@
-# Bridge Sdk
+# Bridge SDK
 
-tooling to help facilitate briding over omnibridges and apply a price to delivery
+A comprehensive toolkit for facilitating cross-chain bridge operations across multiple blockchain networks. This SDK provides low-level building blocks for implementing bridge functionality in decentralized applications.
 
-these are low level tools so they will have to be put together carefully
+## 🎯 Use Cases
 
-they are also in beta stages of development so things may simply change version to version
+### Primary Use Cases
+- **Cross-Chain Bridge Implementation**: Build applications that move tokens between different blockchain networks
+- **Multi-Chain DApp Development**: Create applications that operate across PulseChain, Ethereum, Binance Smart Chain, and other supported networks
+- **Bridge Provider Integration**: Integrate with multiple bridge providers (PulseChain native bridges, TokenSex, etc.)
+- **Token Metadata Management**: Access standardized token information, logos, and network-specific addresses
+- **Fee Calculation**: Calculate and manage bridge fees across different providers and networks
 
-to make things easier, versions are synced across packages
+### Target Applications
+- Cross-chain DEX interfaces
+- Bridge aggregator platforms
+- Multi-chain portfolio management tools
+- DeFi applications requiring cross-chain functionality
+- Wallet applications with bridge features
+
+## 🔧 Core Functionality
+
+### Chain Management
+- **Supported Networks**: PulseChain (0x171), Ethereum (0x1), Binance Smart Chain (0x38), and testnets
+- **Chain Metadata**: Complete chain configurations including RPC URLs, native tokens, and visual assets
+- **Chain Utilities**: Convert between chain IDs and human-readable chain keys
+
+### Token & Bridge Configuration
+- **Token Types**: Standardized token metadata with cross-chain bridge information
+- **Bridge Providers**: Support for multiple bridge providers with different fee structures
+- **Asset Mapping**: Native asset addresses and wrapped token configurations across chains
+
+### Smart Contract Integration
+- **ABIs**: Pre-configured contract ABIs for bridge operations
+- **Contract Addresses**: Deployed contract addresses across supported networks
+- **Type Safety**: Full TypeScript support with strongly typed contract interactions
+
+## 📦 Installation
 
-## install
 ```sh
-npm i --save @gibs/bridge-sdk
+npm install @gibs/bridge-sdk
+# or
+yarn add @gibs/bridge-sdk
 ```
 
-## usage
+## 📖 API Examples
+
+### Types (`@gibs/bridge-sdk/types`)
+
+```typescript
+import type {
+  Token,
+  BridgeKey,
+  TokenList,
+  TokenOut,
+  PerNetworkBridgeLink,
+  Extensions,
+  TokenMetadata,
+  VisualChain
+} from '@gibs/bridge-sdk/types'
+
+// Core token metadata
+const tokenMetadata: TokenMetadata = {
+  name: "Wrapped Ethereum",
+  symbol: "WETH",
+  decimals: 18
+}
+
+// Bridge link information
+const bridgeLink: PerNetworkBridgeLink = {
+  tokenAddress: "0x..." // Address on destination chain
+}
+
+// Token extensions for cross-chain info
+const extensions: Extensions = {
+  wrapped: { address: "0x..." },
+  bridgeInfo: {
+    369: { tokenAddress: "0x..." } // PulseChain mapping
+  }
+}
+
+// Complete token with bridge metadata
+const token: Token = {
+  ...tokenMetadata,
+  address: "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
+  chainId: 1,
+  logoURI: "https://example.com/weth.png",
+  extensions
+}
+
+// Token for output (address can be null)
+const tokenOut: TokenOut = {
+  ...tokenMetadata,
+  address: null, // Can be null for native tokens
+  chainId: 369,
+  logoURI: null
+}
+
+// Bridge route definition
+const bridgeKey: BridgeKey = [
+  'pulsechain',  // Provider
+  '0x1',        // From chain (Ethereum)
+  '0x171'       // To chain (PulseChain)
+]
+
+// Visual chain with logo info
+const visualChain: VisualChain = {
+  id: 369,
+  name: 'PulseChain',
+  chainId: '0x171' as any,
+  logoURI: 'https://example.com/pls.png',
+  alt: 'PulseChain logo'
+  // ... other Chain properties
+}
+```
+
+### Config (`@gibs/bridge-sdk/config`)
+
+```typescript
+import {
+  Chains,
+  Provider,
+  toChain,
+  toChainKey,
+  pathways,
+  validBridgeKeys,
+  inferBridgeKey,
+  pathway,
+  isNative,
+  canChangeUnwrap,
+  defaultAssetIn
+} from '@gibs/bridge-sdk/config'
+
+// Chain enum usage
+console.log(Chains.PLS)    // "0x171"
+console.log(Chains.ETH)    // "0x1"
+
+// Provider enum usage
+console.log(Provider.PULSECHAIN) // "pulsechain"
+
+// Convert numeric chain ID to hex
+const chainHex = toChain(369)     // "0x171"
+const chainHex2 = toChain("369")  // "0x171"
+
+// Convert chain ID to human-readable key
+const chainKey = toChainKey(369)  // "PLS"
+
+// Get all valid bridge routes for environment
+const bridgeRoutes = validBridgeKeys(true) // Production routes
+const testRoutes = validBridgeKeys(false)  // Include testnets
+
+// Find bridge provider for chain pair
+const bridgeKey = inferBridgeKey({
+  fromChain: Chains.ETH,
+  toChain: Chains.PLS,
+  isProd: true
+}) // Returns: ['pulsechain', '0x1', '0x171']
+
+// Get pathway configuration for a bridge route
+const pathwayConfig = pathway(['pulsechain', '0x1', '0x171'], true)
+console.log(pathwayConfig?.from)      // Bridge contract on Ethereum
+console.log(pathwayConfig?.to)        // Bridge contract on PulseChain
+
+// Check if token is native to chain
+const native = isNative(token, bridgeKey) // boolean
+
+// Check if unwrapping is allowed
+const canUnwrap = canChangeUnwrap(bridgeKey, token) // boolean
+
+// Get default asset for bridge route
+const defaultToken = defaultAssetIn(bridgeKey, true) // Default token address
+```
+
+```typescript
+import {
+  nativeAssetOut,
+  nativeTokenSymbol,
+  nativeTokenName,
+  uniV2Routers
+} from '@gibs/bridge-sdk/config'
+
+// Get native wrapped token address for a chain
+const wethAddress = nativeAssetOut[Chains.ETH] // "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
+const wplsAddress = nativeAssetOut[Chains.PLS] // "0xA1077a294dDE1B09bB078844df40758a5D0f9a27"
+
+// Get native token symbols and names
+const ethSymbol = nativeTokenSymbol[Chains.ETH] // "ETH"
+const plsName = nativeTokenName[Chains.PLS]     // "Pulse"
+
+// Get UniV2 router addresses for chain
+const plsRouters = uniV2Routers[Chains.PLS] // Array of router addresses
+```
+
+### Settings (`@gibs/bridge-sdk/settings`)
+
+```typescript
+import {
+  oneEther,
+  basisPoints,
+  bridgePathway,
+  amountToBridge,
+  bridgeCost,
+  estimatedAmountOut,
+  estimatedFee,
+  oneTokenInt,
+  assetOutKey,
+  assetOut
+} from '@gibs/bridge-sdk/settings'
+
+// Common constants
+console.log(oneEther)    // 1000000000000000000n (1e18)
+console.log(basisPoints) // 10000n
+
+// Calculate actual amount to bridge
+const amount = amountToBridge({
+  amountIn: 1000000000000000000n, // 1 ETH
+  assetIn: token,
+}) // Returns 1000000000000000000n or 0n if invalid
+
+// Calculate bridge cost
+const cost = bridgeCost({
+  bridgeKey: ['pulsechain', '0x1', '0x171'],
+  amountIn: oneEther,
+  // ... other parameters
+})
+
+// Estimate output amount after fees
+const outputAmount = estimatedAmountOut({
+  amountIn: oneEther,
+  bridgeKey: ['pulsechain', '0x1', '0x171'],
+  // ... fee parameters
+})
+
+// Calculate fee amount
+const feeAmount = estimatedFee({
+  amountIn: oneEther,
+  feeType: 'percent',
+  // ... other parameters
+})
+
+// Convert amount to "one token" representation
+const oneToken = oneTokenInt({
+  decimals: 18,
+  amount: oneEther
+}) // 1000000000000000000n
+
+// Generate asset out key for caching
+const cacheKey = assetOutKey({
+  bridgeKey: ['pulsechain', '0x1', '0x171'],
+  assetIn: token
+}) // String key for asset lookup
+
+// Get output asset configuration
+const outputAsset = assetOut({
+  bridgeKey: ['pulsechain', '0x1', '0x171'],
+  assetIn: token,
+  // ... other parameters
+})
+```
+
+### Chain Info (`@gibs/bridge-sdk/chain-info`)
+
+```typescript
+import {
+  loadBridgeFees,
+  nativeSymbol,
+  tokenBridgeInfo,
+  fetchPriceCorrective,
+  minBridgeAmountIn,
+  chainMulticall
+} from '@gibs/bridge-sdk/chain-info'
+
+// Load bridge fees for a route
+const fees = await loadBridgeFees({
+  pathway: pathwayConfig,
+  fromChainClient: ethClient,
+  toChainClient: plsClient
+})
+
+// Get native symbol for token, with unwrap logic
+const symbol = nativeSymbol(token, false) // "WETH" or "ETH" if unwrapped
+
+// Get token bridge information
+const bridgeInfo = await tokenBridgeInfo({
+  bridgeKey: ['pulsechain', '0x1', '0x171'],
+  client: ethClient,
+  target: token.address,
+  // ... other parameters
+})
 
-```ts
-// global import
-import * as bridgeSDK from '@gibs/bridge-sdk'
-// or by file
+// Fetch price corrective data
+const priceData = fetchPriceCorrective({
+  bridgeKey: ['pulsechain', '0x1', '0x171'],
+  // ... other parameters
+})
+
+// Get minimum bridge amount
+const minAmount = await minBridgeAmountIn({
+  bridgeKey: ['pulsechain', '0x1', '0x171'],
+  client: ethClient,
+  // ... other parameters
+})
+
+// Create multicall helper for chain
+const multicall = chainMulticall(ethClient)
+// Use for batched contract calls
+```
+
+### Image Links (`@gibs/bridge-sdk/image-links`)
+
+```typescript
+import * as imageLinks from '@gibs/bridge-sdk/image-links'
+
+// Configure image root URL
+imageLinks.setImageRoot('https://cdn.example.com/images/')
+const currentRoot = imageLinks.getImageRoot() // Current root URL
+
+// Get network image URL
+const networkImage = imageLinks.network(1)    // Ethereum logo URL
+const plsImage = imageLinks.network(369)      // PulseChain logo URL
+
+// Get single token image
+const tokenImage = imageLinks.image({
+  chainId: 1,
+  address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
+})
+
+// Get token images for multiple sources
+const tokenImages = imageLinks.images([
+  "1/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2", // WETH on Ethereum
+  "369/0xA1077a294dDE1B09bB078844df40758a5D0f9a27"  // WPLS on PulseChain
+])
+
+// List available images in a directory
+const availableImages = imageLinks.list('tokens/') // Array of image paths
+```
+
+### ABIs (`@gibs/bridge-sdk/abis`)
+
+```typescript
 import * as abis from '@gibs/bridge-sdk/abis'
+
+// Bridge contract ABIs
+const inputBridgeAbi = abis.inputBridge         // Input bridge contract
+const outputBridgeAbi = abis.outputBridge       // Output bridge contract
+const outputRouterAbi = abis.outputRouter       // Output router contract
+
+// Token contract ABIs
+const erc677Abi = abis.erc677                   // ERC677 token contract
+const erc677ExtraAbi = abis.erc677ExtraInput    // With extra input functions
+
+// Router and fee ABIs
+const nativeRouterAbi = abis.nativeRouter       // Native token router
+const feeManagerAbi = abis.feeManager           // Fee management contract
+const univ2RouterAbi = abis.univ2Router         // UniswapV2 router
+
+// Utility ABIs and types
+const feeDeliveryStruct = abis.feeDeliveryStruct // Fee delivery struct ABI
+const homeAmbAbi = abis.homeAmb                  // Home AMB contract
+const pairAbi = abis.pair                        // Pair contract
+
+// Use with viem contract calls
+const contract = getContract({
+  address: bridgeAddress,
+  abi: inputBridgeAbi,
+  client: publicClient
+})
+
+const bridgeFunction = contract.read.someFunction()
+```
+
+### Fee Types (`@gibs/bridge-sdk/fee-type`)
+
+```typescript
+import { FeeType, feeTypeValToKeyMap, type FeeTypeKeys } from '@gibs/bridge-sdk/fee-type'
+
+// Fee type enum
+console.log(FeeType.PERCENT)  // "%"
+console.log(FeeType.GAS_TIP)  // "gas+%"
+console.log(FeeType.FIXED)    // "fixed"
+
+// Fee type keys
+const percentKey: FeeTypeKeys = 'PERCENT'
+const gasTipKey: FeeTypeKeys = 'GAS_TIP'
+
+// Convert fee type value back to key
+const feeTypeKey = feeTypeValToKeyMap.get('%') // "PERCENT"
+const gasKey = feeTypeValToKeyMap.get('gas+%') // "GAS_TIP"
+```
+
+### Chains (`@gibs/bridge-sdk/chains`)
+
+```typescript
+import { chainsMetadata } from '@gibs/bridge-sdk/chains'
+import { Chains } from '@gibs/bridge-sdk/config'
+
+// Get complete chain configuration
+const pulseChain = chainsMetadata[Chains.PLS]
+console.log(pulseChain.name)        // "PulseChain"
+console.log(pulseChain.chainId)     // "0x171"
+console.log(pulseChain.logoURI)     // Chain logo URL
+console.log(pulseChain.rpcUrls.default.http[0]) // Default RPC URL
+
+// Access native currency info
+console.log(pulseChain.nativeCurrency.name)     // "Pulse"
+console.log(pulseChain.nativeCurrency.symbol)   // "PLS"
+console.log(pulseChain.nativeCurrency.decimals) // 18
+
+// Access contract addresses
+console.log(pulseChain.contracts?.multicall3?.address) // Multicall3 address
+console.log(pulseChain.contracts?.ensRegistry?.address) // ENS registry if available
+```
+
+## 📋 API Reference
+
+### Exports
+
+| Export Path | Description |
+|-------------|-------------|
+| `@gibs/bridge-sdk` | Main entry point with all exports |
+| `@gibs/bridge-sdk/types` | TypeScript type definitions |
+| `@gibs/bridge-sdk/config` | Chain IDs, providers, and core configuration |
+| `@gibs/bridge-sdk/chains` | Chain metadata and network configurations |
+| `@gibs/bridge-sdk/abis` | Smart contract ABIs |
+| `@gibs/bridge-sdk/image-links` | Network and token image utilities |
+| `@gibs/bridge-sdk/fee-type` | Fee calculation types and utilities |
+| `@gibs/bridge-sdk/settings` | Bridge settings and configuration |
+| `@gibs/bridge-sdk/chain-info` | Chain-specific bridge information |
+
+### Key Types
+
+```typescript
+// Core chain identifier
+enum Chains {
+  PLS = '0x171',     // PulseChain
+  ETH = '0x1',       // Ethereum
+  BNB = '0x38',      // Binance Smart Chain
+  SEP = '0xaa36a7',  // Sepolia Testnet
+  V4PLS = '0x3af'    // PulseChain V4 Testnet
+}
+
+// Bridge providers
+enum Provider {
+  PULSECHAIN = 'pulsechain',
+  TOKENSEX = 'tokensex'
+}
+
+// Bridge route: [Provider, FromChain, ToChain]
+type BridgeKey = [Provider, Chains, Chains]
+
+// Token with bridge metadata
+interface Token {
+  name: string
+  symbol: string
+  decimals: number
+  address: string
+  chainId: number
+  logoURI: string | null
+  extensions?: {
+    wrapped?: { address: Hex }
+    bridgeInfo?: Record<number, PerNetworkBridgeLink>
+  }
+}
 ```
+
+## ⚠️ Important Notes
+
+- **Beta Stage**: This SDK is in active development. APIs may change between versions.
+- **Version Sync**: All packages in this monorepo maintain synchronized versions.
+- **Low-Level Tools**: These are building blocks that require careful integration.
+- **Dependencies**: Built on top of `@gibs/common` utilities and `viem` for Ethereum interactions.
+
+## 🔗 Dependencies
+
+- `@gibs/common`: Shared utilities for RPC clients, caching, and ERC20 operations
+- `viem`: Type-safe Ethereum library for contract interactions
+- `lodash`: Utility functions for data manipulation
+
+## 📝 Development Status
+
+This package is actively maintained and used in production bridge applications. However, as it's in beta:
+
+- APIs may change in minor version updates
+- New bridge providers and chains are regularly added
+- Breaking changes will be documented in release notes
+
+For the most up-to-date information, check the package version and changelog.

package/dist/src/abis.d.ts

@@ -1,4 +1,4 @@
-/** the abi for the bridge */
+/** the abi for the input bridge */
 export declare const inputBridge: readonly [{
     readonly name: "minPerTx";
     readonly type: "function";
@@ -96,6 +96,7 @@ export declare const inputBridge: readonly [{
     }];
     readonly outputs: readonly [];
 }];
+/** the abi for the input bridge with extra input for the sender origin (tokensex) */
 export declare const inputBridgeExtraInput: readonly [{
     readonly name: "relayTokensAndCall";
     readonly type: "function";
@@ -136,6 +137,7 @@ export declare const inputBridgeExtraInput: readonly [{
     }];
     readonly outputs: readonly [];
 }];
+/** the abi for erc677 tokens */
 export declare const erc677: readonly [{
     readonly name: "transferAndCall";
     readonly type: "function";
@@ -149,6 +151,7 @@ export declare const erc677: readonly [{
     }];
     readonly outputs: readonly [];
 }];
+/** the abi for erc677 tokens bridge with extra input for the sender origin (tokensex) */
 export declare const erc677ExtraInput: readonly [{
     readonly name: "transferAndCall";
     readonly type: "function";
@@ -165,6 +168,7 @@ export declare const erc677ExtraInput: readonly [{
     }];
     readonly outputs: readonly [];
 }];
+/** the abi to read data from the output router */
 export declare const outputRouter: readonly [{
     readonly name: "onTokenBridged";
     readonly type: "function";
@@ -197,6 +201,7 @@ export declare const outputRouter: readonly [{
         readonly type: "address";
     }];
 }];
+/** the abi for the output bridge */
 export declare const outputBridge: readonly [{
     readonly name: "bridgeContract";
     readonly type: "function";
@@ -206,6 +211,7 @@ export declare const outputBridge: readonly [{
         readonly type: "address";
     }];
 }];
+/** the abi for the fee manager */
 export declare const feeManager: readonly [{
     readonly name: "HOME_TO_FOREIGN_FEE";
     readonly type: "function";
@@ -235,6 +241,7 @@ export declare const feeManager: readonly [{
         readonly type: "uint256";
     }];
 }];
+/** the abi for the native router */
 export declare const nativeRouter: readonly [{
     readonly name: "wrapAndRelayTokens";
     readonly type: "function";
@@ -257,6 +264,7 @@ export declare const nativeRouter: readonly [{
     }];
     readonly outputs: readonly [];
 }];
+/** the abi for the native router with extra input for the sender origin (tokensex) */
 export declare const nativeRouterExtraInput: readonly [{
     readonly name: "wrapAndRelayTokens";
     readonly type: "function";
@@ -285,6 +293,7 @@ export declare const nativeRouterExtraInput: readonly [{
     }];
     readonly outputs: readonly [];
 }];
+/** the abi for the univ2 router */
 export declare const univ2Router: readonly [{
     readonly name: "getAmountsOut";
     readonly type: "function";
@@ -300,6 +309,7 @@ export declare const univ2Router: readonly [{
         readonly type: "uint256[]";
     }];
 }];
+/** the abi for the fee delivery struct */
 export declare const feeDeliveryStruct: readonly [{
     readonly type: "tuple";
     readonly components: readonly [{
@@ -312,6 +322,7 @@ export declare const feeDeliveryStruct: readonly [{
         readonly type: "uint256";
     }];
 }];
+/** the abi for the relay tokens direct */
 export declare const relayTokensDirect: readonly [{
     readonly name: "safeExecuteSignaturesWithAutoGasLimit";
     readonly type: "function";
@@ -325,6 +336,7 @@ export declare const relayTokensDirect: readonly [{
     }];
     readonly outputs: readonly [];
 }];
+/** the abi for the home amb */
 export declare const homeAmb: readonly [{
     readonly name: "submitSignature";
     readonly type: "function";
@@ -338,6 +350,7 @@ export declare const homeAmb: readonly [{
     }];
     readonly outputs: readonly [];
 }];
+/** the abi for the univ2 pair */
 export declare const pair: readonly [{
     readonly name: "getReserves";
     readonly type: "function";

package/dist/src/abis.js

@@ -1,5 +1,5 @@
 import { parseAbi, parseAbiParameters } from 'viem';
-/** the abi for the bridge */
+/** the abi for the input bridge */
 export const inputBridge = parseAbi([
     'function minPerTx(address token) external view returns(uint256)',
     'function foreignTokenAddress(address token) external view returns(address)',
@@ -10,45 +10,58 @@ export const inputBridge = parseAbi([
     'function relayTokensAndCall(address token, address _receiver, uint256 _value, bytes memory _data) external',
     'function relayTokens(address token, address _receiver, uint256 _value) external',
 ]);
+/** the abi for the input bridge with extra input for the sender origin (tokensex) */
 export const inputBridgeExtraInput = parseAbi([
     'function relayTokensAndCall(address token, address _receiver, uint256 _value, bytes memory _data, address _senderOrigin) external',
     'function relayTokens(address token, address _receiver, uint256 _value, address _senderOrigin) external',
 ]);
+/** the abi for erc677 tokens */
 export const erc677 = parseAbi([
     'function transferAndCall(address, uint256, bytes calldata) external',
 ]);
+/** the abi for erc677 tokens bridge with extra input for the sender origin (tokensex) */
 export const erc677ExtraInput = parseAbi([
     'function transferAndCall(address, uint256, bytes calldata, address sender) external',
 ]);
+/** the abi to read data from the output router */
 export const outputRouter = parseAbi([
     'function onTokenBridged(address _token, uint256 _value, bytes memory _data) external payable',
     'function WETH() external view returns(address)',
     'function bridge() external view returns(address)',
 ]);
+/** the abi for the output bridge */
 export const outputBridge = parseAbi(['function bridgeContract() external view returns(address)']);
+/** the abi for the fee manager */
 export const feeManager = parseAbi([
     'function HOME_TO_FOREIGN_FEE() public view returns(bytes32)',
     'function FOREIGN_TO_HOME_FEE() public view returns(bytes32)',
     'function getFee(bytes32, address) public view returns(uint256)',
 ]);
+/** the abi for the native router */
 export const nativeRouter = parseAbi([
     'function wrapAndRelayTokens(address receiver) external payable',
     'function relayTokensAndCall(address receiver, bytes calldata data) external payable',
 ]);
+/** the abi for the native router with extra input for the sender origin (tokensex) */
 export const nativeRouterExtraInput = parseAbi([
     'function wrapAndRelayTokens(address receiver, address sender) external payable',
     'function relayTokensAndCall(address receiver, bytes calldata data, address sender) external payable',
 ]);
+/** the abi for the univ2 router */
 export const univ2Router = parseAbi([
     'function getAmountsOut(uint256 amountIn, address[] calldata path) external view returns(uint256[] memory)',
 ]);
+/** the abi for the fee delivery struct */
 export const feeDeliveryStruct = parseAbiParameters('(address, uint256, uint256, uint256)');
+/** the abi for the relay tokens direct */
 export const relayTokensDirect = parseAbi([
     'function safeExecuteSignaturesWithAutoGasLimit(bytes calldata data, bytes calldata signatures) external',
 ]);
+/** the abi for the home amb */
 export const homeAmb = parseAbi([
     'function submitSignature(bytes message, bytes signature) external',
 ]);
+/** the abi for the univ2 pair */
 export const pair = parseAbi([
     'function getReserves() view returns (uint112 reserve0, uint112 reserve1, uint32 blockTimestampLast)',
 ]);