@gibs/bridge-sdk 1.7.2 → 1.9.0

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

@@ -200,6 +200,21 @@ export declare const outputRouter: readonly [{
     readonly outputs: readonly [{
         readonly type: "address";
     }];
+}, {
+    readonly name: "safeExecuteSignaturesWithAutoGasLimit";
+    readonly type: "function";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly type: "address";
+        readonly name: "runner";
+    }, {
+        readonly type: "bytes";
+        readonly name: "_data";
+    }, {
+        readonly type: "bytes";
+        readonly name: "_signatures";
+    }];
+    readonly outputs: readonly [];
 }];
 /** the abi for the output bridge */
 export declare const outputBridge: readonly [{

package/dist/src/abis.js

@@ -28,6 +28,7 @@ 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)',
+    'function safeExecuteSignaturesWithAutoGasLimit(address runner,bytes calldata _data,bytes calldata _signatures) external payable',
 ]);
 /** the abi for the output bridge */
 export const outputBridge = parseAbi(['function bridgeContract() external view returns(address)']);

package/dist/src/chain-info.d.ts

@@ -28,7 +28,7 @@ export declare const links: (({ chainId, target, address, client }: {
     target: Hex;
     address: Hex;
     client: PublicClient;
-}) => Promise<`0x${string}`[]>) & _.MemoizedFunction;
+}) => Promise<[`0x${string}`, `0x${string}`]>) & _.MemoizedFunction;
 /**
  * Returns the token bridge info for the given bridge key, asset in, is prod, from chain client, and to chain client
  * @param bridgeKey - the bridge key

package/dist/src/chains.js

@@ -46,7 +46,7 @@ export const chainsMetadata = {
         alt: 'a gold cube with slits in the middle of each side',
         rpcUrls: {
             default: {
-                http: ['https://bsc-pokt.nodies.app'],
+                http: ['https://bsc-rpc.publicnode.com'],
             },
         },
     },

package/dist/src/config.d.ts

@@ -26,11 +26,11 @@ export declare const toChain: (chainId: number | string) => Chains;
  * @returns the chain key
  */
 export declare const toChainKey: (chainId: number | string) => "ETH" | "PLS" | "BNB" | "SEP" | "V4PLS" | undefined;
-/** The provider of an omnibridge */
-export declare enum Provider {
-    PULSECHAIN = "pulsechain",
-    TOKENSEX = "tokensex"
-}
+export declare const Providers: {
+    readonly PULSECHAIN: "pulsechain";
+    readonly TOKENSEX: "tokensex";
+};
+export type Provider = typeof Providers[keyof typeof Providers];
 /** A map of chains to native asset out addresses */
 export declare const nativeAssetOut: Record<Chains, Hex>;
 /** A map of chains to deprecated native asset out addresses */
@@ -111,3 +111,26 @@ export declare const isUnwrappable: (bridgeKey: BridgeKey | null, assetIn: Pick<
  * @returns boolean
  */
 export declare const canChangeUnwrap: (bridgeKey: BridgeKey, assetIn: Token | null) => boolean;
+export declare const chains: {
+    readonly ethereum: 1;
+    readonly bsc: 56;
+    readonly pulsechain: 369;
+    readonly pulsechainV4: 943;
+    readonly sepolia: 11155111;
+};
+export declare const chainIds: (1 | 56 | 369 | 943 | 11155111)[];
+export type ChainId = (typeof chainIds)[number];
+export type Side = 'home' | 'foreign';
+export type MinimalKey = `${ChainId}-${Hex}`;
+export type PathwayInfo = {
+    pair: string;
+    key: string;
+    home: Hex;
+    foreign: Hex;
+};
+export type ProviderHomeChainEntry = Partial<Record<ChainId, PathwayInfo[]>>;
+export type ProviderEntries = Partial<Record<ChainId, ProviderHomeChainEntry>>;
+export type BridgeConfig = Record<Provider, ProviderEntries>;
+export declare const bridgeConfigs: BridgeConfig;
+export declare const HOME_TO_FOREIGN_FEE: `0x${string}`;
+export declare const FOREIGN_TO_HOME_FEE: `0x${string}`;