@brotocol-xyz/bro-sdk is a TypeScript SDK designed to integrate with Brotocol's on-chain and off-chain infrastructure. It is web3 library-agnostic, meaning you can use your preferred library to send and broadcast transactions while the SDK handles the rest.
đ Brotocol isn't just a bridgeâit's the liquidity layer for Bitcoin and the essential connector for Bitcoin DeFi đ
With pnpm:
pnpm install @brotocol-xyz/bro-sdk
The BroSDK class provides the core functions of the library. To create an instance:
import { BroSDK } from "@brotocol-xyz/bro-sdk"
const sdk = new BroSDK()
For the full API reference, including a full list of available methods and their usage, visit the SDK Documentation.
The KnownChainId namespace defines types and utility functions for all supported mainnet and testnet networks.
Usage example:
import { KnownChainId } from "@brotocol-xyz/bro-sdk"
// Bitcoin
const bitcoinChainId = KnownChainId.Bitcoin.Mainnet
const bitcoinTestnetChainId = KnownChainId.Bitcoin.Testnet
// EVM
const ethereumChainId = KnownChainId.EVM.Ethereum
const ethereumTestnetChainId = KnownChainId.EVM.Sepolia
// Utility function usage example
KnownChainId.isEVMTestnetChain(KnownChainId.EVM.Sepolia) // Returns true
KnownChainId.isEVMMainnetChain(KnownChainId.EVM.Sepolia) // Returns false
Runes and BRC20 metaprotocols are treated as distinct chains within the SDK, even though they share Bitcoin as the underlying blockchain.
Token support is dynamic, meaning new tokens can be added without requiring SDK updates. Instead of relying on a static list, the SDK provides methods to fetch supported tokens at runtime. Tokens are represented using the TokenId type â this is how the library internally handles and identifies tokens.
Also, check the KnownTokenId namespace to see types and utility functions for all supported tokens.
TokenId// For BRC20 provide the tick symbol
const brc20Token = await sdk.brc20TickToBRC20Token(
KnownChainId.BRC20.Mainnet,
"alex$",
)
// For Runes provide the runes ID
const runesToken = await sdk.runesIdToRunesToken(
KnownChainId.Runes.Mainnet,
"500:20",
)
// For Stacks provide the contract address
const stacksToken = await sdk.stacksAddressToStacksToken(
KnownChainId.Stacks.Mainnet,
{
deployerAddress: "SP2XD7417HGPRTREMKF748VNEQPDRR0RMANB7X1NK",
contractName: "token-abtc",
},
)
// For EVM tokens provide the contract address
const evmToken = await sdk.evmAddressToEVMToken(
KnownChainId.EVM.Ethereum,
"0x31761a152F1e96F966C041291644129144233b0B",
)
If a token is unsupported, these functions return Promise<undefined>.
Some Stacks and EVM tokens are still statically defined in KnownTokenId.Stacks and KnownTokenId.EVM for backward compatibility, but future additions will also be dynamically handled.
TokenId values might change in future updates (no backward compatibility guaranteed). To ensure validity, always get fresh TokenIds at runtime using SDK methodsânever cache them or construct them manually.
// Get all Brotocol available routes
const allRoutes = await sdk.getPossibleRoutes()
// Get routes filtered by source chain
const routesBySourceChain = await sdk.getPossibleRoutes({
fromChain: KnownChainId.BRC20.Mainnet,
})
// Get routes filtered by source and target chain
const routesBySourceAndTargetChain = await sdk.getPossibleRoutes({
fromChain: KnownChainId.BRC20.Mainnet,
toChain: KnownChainId.EVM.Ethereum,
})
// Check if a specific token pair is supported for at least one route
const isSupported = await sdk.isSupportedRoute({
fromChain: KnownChainId.BRC20.Mainnet,
toChain: KnownChainId.EVM.Ethereum,
fromToken: brc20Token as KnownTokenId.BRC20Token,
toToken: evmToken as KnownTokenId.EVMToken,
})
// If the token pair is supported, get available routes for that pair
if (isSupported) {
const routesByPair = await sdk.getPossibleRoutes({
fromChain: KnownChainId.BRC20.Mainnet,
toChain: KnownChainId.EVM.Ethereum,
fromToken: brc20Token as KnownTokenId.BRC20Token,
toToken: evmToken as KnownTokenId.EVMToken,
})
}
The SDK provides three main methods for handling cross-chain asset transfers.
bridgeInfoFrom methodsRetrieve data to perform a cross-chain transfer:
These methods do not check the bridge's min/max amount limits. These checks are enforced on-chain, and the transaction will revert if the amount conditions are not met.
import { toSDKNumberOrUndefined } from "@brotocol-xyz/bro-sdk"
// Retrieve bridge info to perform a transfer from Stacks to EVM
const bridgeInfo = await sdk.bridgeInfoFromStacks({
fromChain: KnownChainId.Stacks.Mainnet,
toChain: KnownChainId.EVM.Ethereum,
fromToken: stacksToken as KnownTokenId.StacksToken,
toToken: evmToken as KnownTokenId.EVMToken,
amount: toSDKNumberOrUndefined(100_000_000), // Assume 6 decimals
})
estimateBridgeTransactionFrom methodsEstimate the transaction fee and virtual size (vbytes) for bridging from Bitcoin-based networks (Bitcoin, Runes, BRC20). Fees are calculated as:
fee = virtualSize [vbytes] Ă networkFeeRate [sat/vbyte]
networkFeeRate is provided by dev. Typical fee rates range from 1â100 sat/vbyte, depending on network congestion and desired confirmation speed. See this reference for more on transaction size.
Why is this important? Miners prioritize transactions with higher fees per vbyte. Accurately estimating the transaction virtual size allows to set an appropriate fee, so the transaction is confirmed in a timely manner.
See the examples/bridgeFrom/Bitcoin.ts file for usage example.
bridgeFrom methodsOnce the route is validated, the cross-chain transfer can be initiated. These methods construct and submit the transaction on the source chain.
The SDK does not always broadcast transactionsâit provides the data required to sign and send them. The sendTransaction function parameter must be implemented by the developer using their preferred web3 library. The SDK provides the necessary arguments, including contract addresses, function to call and call data.
Examples on how to use the bridgeFrom methods can be found in the examples folder.
This project is licensed under the terms of the MIT license.