From 10a90b7f1bdbf3ad3f2b6916603f9e0cadaa973e Mon Sep 17 00:00:00 2001 From: "ignacio.pena@coinfabrik.com" Date: Fri, 23 Aug 2024 18:58:03 -0300 Subject: [PATCH 1/7] add typedoc comments --- src/XLinkSDK.ts | 219 ++++++++++++++++++++++++++++++++++++ src/utils/types/knownIds.ts | 72 +++++++++++- src/xlinkSdkUtils/types.ts | 17 +++ 3 files changed, 304 insertions(+), 4 deletions(-) diff --git a/src/XLinkSDK.ts b/src/XLinkSDK.ts index c86e627..71dfeaf 100644 --- a/src/XLinkSDK.ts +++ b/src/XLinkSDK.ts @@ -140,6 +140,19 @@ export class XLinkSDK { } } + /** + * This function retrieves the list of supported routes for token transfers between blockchain + * networks, filtered based on optional conditions. It aggregates the results from different + * blockchain networks (Stacks, EVM, Bitcoin) to return a list of possible routes. + * @param conditions - An optional object containing the conditions for filtering the supported routes: + * - `fromChain?: ChainId` - The ID of the source blockchain (optional). + * - `toChain?: ChainId` - The ID of the destination blockchain (optional). + * - `fromToken?: TokenId` - The ID of the token being transferred from the source blockchain (optional). + * - `toToken?: TokenId` - The ID of the token expected on the destination blockchain (optional). + * + * @returns A promise that resolves with an array of `KnownRoute` objects, each representing a + * possible route for the token transfer. + */ async getSupportedRoutes( conditions?: GetSupportedRoutesFn_Conditions, ): Promise { @@ -154,17 +167,70 @@ export class XLinkSDK { stacksAddressFromStacksToken = stacksAddressFromStacksToken stacksAddressToStacksToken = stacksAddressToStacksToken + + /** + * This function provides detailed information about token transfers from the Stacks network to other supported + * blockchain networks, including Bitcoin and EVM-compatible chains. It verifies the validity of the transfer + * route and retrieves bridge information based on the destination chain and tokens. + * @param input - An object containing the input parameters required for retrieving bridge information: + * - `fromChain: ChainId` - The ID of the source blockchain (Stacks in this case). + * - `toChain: ChainId` - The ID of the destination blockchain (Bitcoin, EVM-compatible chains, etc.). + * - `fromToken: TokenId` - The token being transferred from the Stacks network. + * - `toToken: TokenId` - The token expected on the destination chain. + * - `amount: SDKNumber` - The amount of tokens involved in the transfer. + * + * @returns A promise that resolves with an object containing detailed information about the token transfer, including: + * - `fromChain: KnownChainId.KnownChain` - The source blockchain. + * - `fromToken: KnownTokenId.KnownToken` - The token being transferred from the Stacks network. + * - `toChain: KnownChainId.KnownChain` - The destination blockchain. + * - `toToken: KnownTokenId.KnownToken` - The token expected on the destination chain. + * - `fromAmount: SDKNumber` - The amount of tokens being transferred. + * - `toAmount: SDKNumber` - The amount of tokens expected on the destination chain after the transfer. + * - `feeAmount: SDKNumber` - The fee amount deducted during the transfer. + * - `transferProphets: PublicTransferProphet[]` - An array of objects containing additional details about the transfer, + * such as fees, minimum and maximum bridge amounts, and whether the transfer route is paused. + * @throws UnsupportedBridgeRouteError - If the provided route between the source and destination + * chains or tokens is unsupported. + */ bridgeInfoFromStacks( input: BridgeInfoFromStacksInput, ): Promise { return bridgeInfoFromStacks(this.sdkContext, input) } + + /** + * This function facilitates the transfer of tokens from the Stacks network to other supported blockchain + * networks, including Bitcoin and EVM-compatible chains. It validates the route and calls the appropriate + * bridging function based on the destination chain and tokens involved. + * @param input - An object containing the input parameters required for the bridging operation: + * - `fromChain: ChainId` - The ID of the source blockchain. + * - `toChain: ChainId` - The ID of the destination blockchain (Bitcoin, EVM, etc.). + * - `fromToken: TokenId` - The token being transferred from the source chain. + * - `toToken: TokenId` - The token expected on the destination chain. + * - `toAddress: string` - The recipient's address on the destination blockchain. + * - `amount: SDKNumber` - The amount of tokens to transfer. + * - `sendTransaction: TODO. + * + * @returns A promise that resolves with the transaction ID (`txid`) of the bridging operation. + * @throws UnsupportedBridgeRouteError - If the provided route between the source and destination + * chains or tokens is unsupported. + */ bridgeFromStacks( input: BridgeFromStacksInput, ): Promise { return bridgeFromStacks(this.sdkContext, input) } + /** + * This function retrieves the contract address of a specific type of contract + * (e.g., a bridge endpoint) on a given EVM-compatible blockchain. + * @param chain - The ID of the EVM-compatible blockchain where the contract is deployed. + * @param contractType - The type of contract (e.g., `PublicEVMContractType.BridgeEndpoint`) + * for which the address is to be retrieved. + * + * @returns A promise that resolves with the contract address of the specified type, or + * `undefined` if the chain is not EVM-compatible or if the address cannot be retrieved. + */ async getEVMContractAddress( chain: ChainId, contractType: PublicEVMContractType, @@ -177,6 +243,15 @@ export class XLinkSDK { } return } + + /** + * This function retrieves the contract address of a specific token on a given EVM-compatible blockchain. + * @param chain - The ID of the EVM-compatible blockchain where the token contract is deployed. + * @param token - The specific token ID for which the contract address is to be retrieved. + * + * @returns A promise that resolves with the contract address of the token, or `undefined` if the + * chain is not EVM-compatible or if the contract address cannot be retrieved. + */ async evmAddressFromEVMToken( chain: ChainId, token: KnownTokenId.EVMToken, @@ -185,6 +260,15 @@ export class XLinkSDK { const info = await getEVMTokenContractInfo(this.sdkContext, chain, token) return info?.tokenContractAddress } + + /** + * This function maps a given contract address on an EVM-compatible blockchain to its corresponding known token ID. + * @param chain - The ID of the EVM-compatible blockchain where the contract is deployed. + * @param address - The contract address on the EVM-compatible blockchain. + * + * @returns A promise that resolves with the known token ID corresponding to the provided contract + * address, or `undefined` if the token ID cannot be found or if the chain is not EVM-compatible. + */ async evmAddressToEVMToken( chain: ChainId, address: EVMAddress, @@ -192,19 +276,70 @@ export class XLinkSDK { if (!KnownChainId.isEVMChain(chain)) return return getEVMToken(this.sdkContext, chain, address) } + bridgeInfoFromEVM( input: BridgeInfoFromEVMInput, ): Promise { return bridgeInfoFromEVM(this.sdkContext, input) } + + /** + * This function facilitates the transfer of tokens from an EVM-compatible blockchain to other supported + * blockchain networks, including Stacks, Bitcoin, and other EVM-compatible chains. It validates the + * route and calls the appropriate bridging function based on the destination chain and tokens involved. + * @param input - An object containing the input parameters required for the bridging operation: + * - `fromChain: ChainId` - The ID of the source blockchain (an EVM-compatible chain in this case). + * - `toChain: ChainId` - The ID of the destination blockchain (Stacks, Bitcoin, or another EVM-compatible chain). + * - `fromToken: TokenId` - The token being transferred from the EVM-compatible blockchain. + * - `toToken: TokenId` - The token expected on the destination chain. + * - `toAddress: string` - The recipient's address on the destination blockchain. + * - `toAddressScriptPubKey?: Uint8Array` - The script public key for the `toAddress`, required when the destination is a Bitcoin chain. + * - `amount: SDKNumber` - The amount of tokens to transfer. + * - `sendTransaction: TODO. + * + * @returns A promise that resolves with the transaction hash (`txHash`) of the bridging operation. + * @throws UnsupportedBridgeRouteError - If the provided route between the source and destination + * chains or tokens is unsupported. + */ bridgeFromEVM(input: BridgeFromEVMInput): Promise { return bridgeFromEVM(this.sdkContext, input) } + + /** + * This function retrieves a list of time-locked assets for a given wallet address across multiple EVM-compatible + * blockchain networks. It queries smart contracts to find and return information about the assets that are + * currently locked in time-based agreements. + * @param input - An object containing the input parameters required for retrieving time-locked assets: + * - `walletAddress: EVMAddress` - The address of the wallet for which to retrieve the time-locked assets. + * - `chains: KnownChainId.EVMChain[]` - An array of EVM-compatible blockchains to query for locked assets. + * + * @returns A promise that resolves with an object containing a list of time-locked assets: + * - `assets: TimeLockedAsset[]` - An array of objects, each representing a time-locked asset, including: + * - `id: string` - The unique identifier of the time-locked agreement. + * - `chain: KnownChainId.EVMChain` - The blockchain where the asset is locked. + * - `token: KnownTokenId.EVMToken` - The token that is locked. + * - `amount: SDKNumber` - The amount of the token that is locked. + * - `releaseTime: Date` - The time when the asset is scheduled to be released. + * + * @throws UnsupportedChainError - If any of the provided EVM chains is unsupported or invalid. + */ getTimeLockedAssetsFromEVM( input: GetTimeLockedAssetsInput, ): Promise { return getTimeLockedAssetsFromEVM(this.sdkContext, input) } + + /** + * This function facilitates the claiming of time-locked assets on EVM-compatible chains. It uses smart + * contract functions to execute the release of locked assets based on predefined conditions. + * @param input - An object containing the input parameters required for claiming time-locked assets: + * - `chain: KnownChainId.EVMChain` - The ID of the EVM-compatible blockchain where the assets are locked. + * - `lockedAssetIds: string[]` - An array of IDs representing the locked assets to be claimed. + * - `sendTransaction: TODO. + * + * @returns A promise that resolves with the transaction hash (`txHash`) of the claiming operation, or `undefined` if the operation fails. + * @throws UnsupportedChainError - If the provided EVM chain is unsupported or invalid. + */ claimTimeLockedAssetsFromEVM( input: ClaimTimeLockedAssetsInput, ): Promise { @@ -219,12 +354,78 @@ export class XLinkSDK { if (!KnownChainId.isKnownChain(toChain)) return return getBTCPegInAddress(fromChain, toChain) } + + /** + * This function provides detailed information about token transfers from the Bitcoin network to other supported + * blockchain networks, including Stacks and EVM-compatible chains. It verifies the validity of the transfer route + * and retrieves bridge information based on the destination chain. + * @param info - An object containing the input parameters required for retrieving bridge information: + * - `fromChain: ChainId` - The ID of the source blockchain. + * - `toChain: ChainId` - The ID of the destination blockchain (Stacks, EVM, etc.). + * - `amount: SDKNumber` - The amount of tokens involved in the transfer. + * + * @returns A promise that resolves with an object containing detailed information about the token transfer, including: + * - `fromChain: KnownChainId.KnownChain` - The source blockchain. + * - `fromToken: KnownTokenId.KnownToken` - The token being transferred from the Bitcoin network. + * - `toChain: KnownChainId.KnownChain` - The destination blockchain. + * - `toToken: KnownTokenId.KnownToken` - The token expected on the destination chain. + * - `fromAmount: SDKNumber` - The amount of tokens being transferred. + * - `toAmount: SDKNumber` - The amount of tokens expected on the destination chain after the transfer. + * - `feeAmount: SDKNumber` - The fee amount deducted during the transfer. + * - `transferProphets: PublicTransferProphet[]` - An array of objects containing additional details about the transfer, + * such as fees, minimum and maximum bridge amounts, and whether the transfer route is paused. + * @throws UnsupportedBridgeRouteError - If the provided route between the source and destination + * chains is unsupported. + */ bridgeInfoFromBitcoin = bridgeInfoFromBitcoin + + /** + * This function estimates the transaction fee and vSize for move or swap tokens from the Bitcoin network + * to other supported blockchain networks, including Stacks and EVM-compatible chains. + * @param input - An object containing the input parameters required for estimating the transaction: + * - `fromChain: ChainId` - The ID of the source blockchain (Bitcoin in this case). + * - `toChain: ChainId` - The ID of the destination blockchain (Stacks, EVM-compatible chains, etc.). + * - `fromToken: TokenId` - The token being transferred from the Bitcoin network. + * - `toToken: TokenId` - The token expected on the destination chain. + * - `fromAddress: string` - The source address on the Bitcoin network. + * - `fromAddressScriptPubKey: Uint8Array` - The script public key of the source address. + * - `toAddress: string` - The destination address on the target blockchain. + * - `amount: SDKNumber` - The amount of tokens to be transferred. + * - `networkFeeRate: bigint` - The fee rate for the Bitcoin network. + * - `reselectSpendableUTXOs: ReselectSpendableUTXOsFn` - A function to reselect the spendable UTXOs. + * + * @returns A promise that resolves with an object containing the estimated transaction details: + * - `fee: SDKNumber` - The estimated transaction fee. + * - `estimatedVSize: SDKNumber` - The estimated vSize of the transaction. + * @throws UnsupportedBridgeRouteError - If the provided route between the source and destination + * chains or tokens is unsupported. + */ estimateBridgeTransactionFromBitcoin( input: EstimateBridgeTransactionFromBitcoinInput, ): Promise { return estimateBridgeTransactionFromBitcoin(this.sdkContext, input) } + /** + * This function facilitates the transfer of tokens from the Bitcoin network to other supported + * blockchain networks. It checks the validity of the route and then calls the appropriate + * bridging function based on the destination chain. + * @param input - An object containing the input parameters required for the bridging operation: + * - `fromChain: ChainId` - The ID of the source blockchain. + * - `toChain: ChainId` - The ID of the destination blockchain (Stacks, EVM, etc.). + * - `fromToken: TokenId` - The token being transferred from the Bitcoin network. + * - `toToken: TokenId` - The token expected on the destination chain. + * - `fromAddress: string` - The source address on the Bitcoin network. + * - `fromAddressScriptPubKey: Uint8Array` - The script public key corresponding to the `fromAddress`. + * - `toAddress: string` - The recipient's address on the destination blockchain. + * - `amount: SDKNumber` - The amount of tokens to transfer. + * - `networkFeeRate: bigint` - The network fee rate to be used for the transaction. + * - `reselectSpendableUTXOs: ReselectSpendableUTXOsFn`. + * - `signPsbt: BridgeFromBitcoinInput_signPsbtFn`. + * + * @returns A promise that resolves with the transaction ID (`tx`) of the bridging operation. + * @throws UnsupportedBridgeRouteError - If the provided route between the source and destination + * chains or tokens is unsupported. + */ bridgeFromBitcoin( input: BridgeFromBitcoinInput, ): Promise { @@ -232,6 +433,14 @@ export class XLinkSDK { } } +/** + * This function retrieves the contract address associated with a specific token on the Stacks blockchain. + * @param chain - The ID of the Stacks blockchain. + * @param token - The specific token ID for which the contract address is to be retrieved. + * + * @returns A promise that resolves with the contract address associated with the specified token, + * or `undefined` if the chain is not a Stacks chain or if the contract address cannot be retrieved. + */ async function stacksAddressFromStacksToken( chain: ChainId, token: KnownTokenId.StacksToken, @@ -244,6 +453,16 @@ async function stacksAddressFromStacksToken( contractName: info.contractName, } } + +/** + * This function maps a given Stacks contract address to its corresponding known token ID. + * @param chain - The ID of the Stacks blockchain. + * @param address - The contract address on the Stacks blockchain. + * + * @returns A promise that resolves with the known token ID corresponding to the provided + * contract address, or `undefined` if the chain is not a Stacks chain or if the token ID + * cannot be found. + */ async function stacksAddressToStacksToken( chain: ChainId, address: StacksContractAddress, diff --git a/src/utils/types/knownIds.ts b/src/utils/types/knownIds.ts index 84ec72c..2caf080 100644 --- a/src/utils/types/knownIds.ts +++ b/src/utils/types/knownIds.ts @@ -4,49 +4,77 @@ import { checkNever } from "../typeHelpers" const chainId = (value: T): ChainId => value as any const tokenId = (value: T): TokenId => value as any +/** + * The `KnownTokenId` namespace provides types of tokens supported by the SDK, + * including Bitcoin, EVM-compatible tokens, and Stacks tokens. + */ export namespace KnownTokenId { + /** Represents a known token supported by the SDK. */ export type KnownToken = BitcoinToken | EVMToken | StacksToken export function isKnownToken(value: TokenId): value is KnownToken { return isBitcoinToken(value) || isEVMToken(value) || isStacksToken(value) } + /** A namespace that contains constants and types for Bitcoin tokens. */ export namespace Bitcoin { + /** Represents the Bitcoin token ID (BTC). */ export const BTC = tokenId("btc-btc") } + /** This type includes all known Bitcoin tokens. */ export type BitcoinToken = (typeof _allKnownBitcoinTokens)[number] export function isBitcoinToken(value: TokenId): value is BitcoinToken { return _allKnownBitcoinTokens.includes(value as any) } + /** A namespace that contains constants and types for EVM-compatible tokens. */ export namespace EVM { + /** Represents the USDT token ID on EVM-compatible blockchains. */ export const USDT = tokenId("evm-usdt") + /** Represents the LUNR token ID on EVM-compatible blockchains. */ export const LUNR = tokenId("evm-lunr") + /** Represents the WBTC token ID on EVM-compatible blockchains. */ export const WBTC = tokenId("evm-wbtc") + /** Represents the BTCB token ID on EVM-compatible blockchains. */ export const BTCB = tokenId("evm-btcb") // wrapped tokens + /** Represents the aBTC token ID on EVM-compatible blockchains. */ export const aBTC = tokenId("evm-abtc") + /** Represents the sUSDT token ID on EVM-compatible blockchains. */ export const sUSDT = tokenId("evm-susdt") + /** Represents the ALEX token ID on EVM-compatible blockchains. */ export const ALEX = tokenId("evm-alex") + /** Represents the SKO token ID on EVM-compatible blockchains. */ export const SKO = tokenId("evm-sko") + /** Represents the vLiSTX token ID on EVM-compatible blockchains. */ export const vLiSTX = tokenId("evm-vlistx") + /** Represents the vLiALEX token ID on EVM-compatible blockchains. */ export const vLiALEX = tokenId("evm-vlialex") } + /** This type includes all known tokens on EVM-compatible blockchains. */ export type EVMToken = (typeof _allKnownEVMTokens)[number] export function isEVMToken(value: TokenId): value is EVMToken { return _allKnownEVMTokens.includes(value as any) } - + /** A namespace that contains constants and types for Stacks tokens. */ export namespace Stacks { + /** Represents the sUSDT token ID on the Stacks blockchain. */ export const sUSDT = tokenId("stx-susdt") + /** Represents the sLUNR token ID on the Stacks blockchain. */ export const sLUNR = tokenId("stx-slunr") + /** Represents the aBTC token ID on the Stacks blockchain. */ export const aBTC = tokenId("stx-abtc") + /** Represents the ALEX token ID on the Stacks blockchain. */ export const ALEX = tokenId("stx-alex") + /** Represents the sSKO token ID on the Stacks blockchain. */ export const sSKO = tokenId("stx-ssko") + /** Represents the vLiSTX token ID on the Stacks blockchain. */ export const vLiSTX = tokenId("stx-vlistx") + /** Represents the vLiALEX token ID on the Stacks blockchain. */ export const vLiALEX = tokenId("stx-vlialex") } + /** This type includes all known tokens on the Stacks blockchain. */ export type StacksToken = (typeof _allKnownStacksTokens)[number] export function isStacksToken(value: TokenId): value is StacksToken { return _allKnownStacksTokens.includes(value as any) @@ -56,86 +84,122 @@ export const _allKnownBitcoinTokens = Object.values(KnownTokenId.Bitcoin) export const _allKnownEVMTokens = Object.values(KnownTokenId.EVM) export const _allKnownStacksTokens = Object.values(KnownTokenId.Stacks) +/** + * The `KnownChainId` namespace provides types of blockchain networks + * supported by the SDK, including Bitcoin, EVM-compatible chains, and Stacks. + */ export namespace KnownChainId { + /** Represents a known blockchain network supported by the SDK. */ export type KnownChain = BitcoinChain | EVMChain | StacksChain export function isKnownChain(value: ChainId): value is KnownChain { return isBitcoinChain(value) || isEVMChain(value) || isStacksChain(value) } - + /** A namespace that contains constants and types for Bitcoin networks. */ export namespace Bitcoin { + /** Represents the Bitcoin mainnet chain ID. */ export const Mainnet = chainId("bitcoin-mainnet") + /** Represents the Bitcoin testnet chain ID. */ export const Testnet = chainId("bitcoin-testnet") } + /** Represents a Bitcoin blockchain network. */ export type BitcoinChain = (typeof _allKnownBitcoinChains)[number] export function isBitcoinChain(value: ChainId): value is BitcoinChain { return _allKnownBitcoinChains.includes(value as any) } - + /** A namespace that contains constants and types for EVM-compatible networks. */ export namespace EVM { // Mainnet + /** Represents the Ethereum mainnet chain ID. */ export const Ethereum = chainId("evm-ethereum") + /** Represents the Ethereum testnet chain ID. */ export const Sepolia = chainId("evm-sepolia") // BNB Smart Chain + /** Represents the BNB Smart Chain mainnet chain ID. */ export const BSC = chainId("evm-bsc") + /** Represents the BNB Smart Chain testnet chain ID. */ export const BSCTestnet = chainId("evm-bsctestnet") // CoreDAO + /** Represents the CoreDAO mainnet chain ID. */ export const CoreDAO = chainId("evm-coredao") + /** Represents the CoreDAO testnet chain ID. */ export const CoreDAOTestnet = chainId("evm-coredao-testnet") // B2 Bsquared + /** Represents the Bsquared mainnet chain ID. */ export const Bsquared = chainId("evm-bsquared") + /** Represents the Bsquared testnet chain ID. */ export const BsquaredTestnet = chainId("evm-bsquared-testnet") // BOB + /** Represents the BOB mainnet chain ID. */ export const BOB = chainId("evm-bob") + /** Represents the BOB testnet chain ID. */ export const BOBTestnet = chainId("evm-bob-testnet") // Bitlayer + /** Represents the Bitlayer mainnet chain ID. */ export const Bitlayer = chainId("evm-bitlayer") + /** Represents the Bitlayer testnet chain ID. */ export const BitlayerTestnet = chainId("evm-bitlayer-testnet") // Lorenzo + /** Represents the Lorenzo mainnet chain ID. */ export const Lorenzo = chainId("evm-lorenzo") + /** Represents the Lorenzo testnet chain ID. */ export const LorenzoTestnet = chainId("evm-lorenzo-testnet") // Merlin + /** Represents the Merlin mainnet chain ID. */ export const Merlin = chainId("evm-merlin") + /** Represents the Merlin testnet chain ID. */ export const MerlinTestnet = chainId("evm-merlin-testnet") // AILayer + /** Represents the AILayer mainnet chain ID. */ export const AILayer = chainId("evm-ailayer") + /** Represents the AILayer testnet chain ID. */ export const AILayerTestnet = chainId("evm-ailayer-testnet") // Mode + /** Represents the Mode mainnet chain ID. */ export const Mode = chainId("evm-mode") + /** Represents the Mode testnet chain ID. */ export const ModeTestnet = chainId("evm-mode-testnet") // X Layer + /** Represents the XLayer mainnet chain ID. */ export const XLayer = chainId("evm-xlayer") + /** Represents the XLayer testnet chain ID. */ export const XLayerTestnet = chainId("evm-xlayer-testnet") } + /** Represents a mainnet EVM-compatible blockchain network. */ export type EVMMainnetChain = (typeof _allKnownEVMMainnetChains)[number] export function isEVMMainnetChain(value: ChainId): value is EVMMainnetChain { return _allKnownEVMMainnetChains.includes(value as any) } - + /** Represents a testnet EVM-compatible blockchain network. */ export type EVMTestnetChain = (typeof _allKnownEVMTestnetChains)[number] export function isEVMTestnetChain(value: ChainId): value is EVMTestnetChain { return _allKnownEVMTestnetChains.includes(value as any) } + /** Represents an EVM-compatible blockchain network. */ export type EVMChain = (typeof _allKnownEVMChains)[number] export function isEVMChain(value: ChainId): value is EVMChain { return _allKnownEVMChains.includes(value as any) } + /** A namespace that contains constants and types for Stacks blockchain networks. */ export namespace Stacks { + /** Represents the Stacks mainnet chain ID. */ export const Mainnet = chainId("stacks-mainnet") + /** Represents the Stacks testnet chain ID. */ export const Testnet = chainId("stacks-testnet") } + /** Represents a Stacks blockchain network. */ export type StacksChain = (typeof _allKnownStacksChains)[number] export function isStacksChain(value: ChainId): value is StacksChain { return _allKnownStacksChains.includes(value as any) diff --git a/src/xlinkSdkUtils/types.ts b/src/xlinkSdkUtils/types.ts index 55cbc15..811c3d4 100644 --- a/src/xlinkSdkUtils/types.ts +++ b/src/xlinkSdkUtils/types.ts @@ -7,7 +7,13 @@ type SDKBrandedLiteral< T extends string | number, > = `${T} (XLinkSDK ${Type})` +/** + * Represents a unique identifier for a blockchain network. + */ export type ChainId = SDKBrandedLiteral<"ChainId", T> +/** + * Represents a unique identifier for a cryptocurrency token. + */ export type TokenId = SDKBrandedLiteral<"TokenId", T> export type SDKNumber = SDKBrandedLiteral<"number", string> @@ -57,7 +63,18 @@ export interface StacksContractAddress { contractName: string } +/** + * Represents the type of public EVM contracts that are accessible through the SDK. + * The `PublicEVMContractType` is tied to the specific `BridgeEndpoint` contract type defined + * in the `EVMEndpointContract` namespace. + */ export type PublicEVMContractType = typeof PublicEVMContractType.BridgeEndpoint +/** + * A namespace that defines the public contract types available in the SDK for EVM-compatible blockchains. + * This namespace currently includes only the `BridgeEndpoint` contract type, which corresponds to + * the main contract used for bridging assets across EVM-compatible blockchains. + */ export namespace PublicEVMContractType { + /** Represents the bridge endpoint contract type in an EVM-compatible blockchain. */ export const BridgeEndpoint = EVMEndpointContract.BridgeEndpoint } From d8e27c94522fae3b5dcb08dda2068a8993a0933b Mon Sep 17 00:00:00 2001 From: david weil Date: Fri, 23 Aug 2024 20:22:56 -0300 Subject: [PATCH 2/7] fix merge error --- src/utils/types/knownIds.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/utils/types/knownIds.ts b/src/utils/types/knownIds.ts index 0160b53..6b5216b 100644 --- a/src/utils/types/knownIds.ts +++ b/src/utils/types/knownIds.ts @@ -173,6 +173,10 @@ export namespace KnownChainId { export const XLayer = chainId("evm-xlayer") /** Represents the XLayer testnet chain ID. */ // export const XLayerTestnet = chainId("evm-xlayer-testnet") + // Arbitrum + /** Represents the Arbitrum mainnet chain ID. */ + export const Arbitrum = chainId("evm-arbitrum") + // export const ArbitrumTestnet = chainId("evm-arbitrum-testnet") } /** Represents a mainnet EVM-compatible blockchain network. */ From 54a2ee9f186ce4578c2b4adf891940d111e9b49f Mon Sep 17 00:00:00 2001 From: david weil Date: Fri, 23 Aug 2024 20:27:10 -0300 Subject: [PATCH 3/7] update dev-dependencies to include typedoc --- package.json | 1 + pnpm-lock.yaml | 160 ++++++++++++++++++++++++++++++++++++++++++------- 2 files changed, 139 insertions(+), 22 deletions(-) diff --git a/package.json b/package.json index 3c21e1a..e534963 100644 --- a/package.json +++ b/package.json @@ -57,6 +57,7 @@ "prettier": "^3.2.5", "tsup": "^8.0.2", "tsx": "^4.7.2", + "typedoc": "^0.26.6", "typescript": "^5.4.5", "viem": "^2.15.1", "vitest": "^1.4.0" diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 13255e5..da388c3 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -21,7 +21,7 @@ importers: devDependencies: '@c4605/toolconfs': specifier: ^5.3.0 - version: 5.3.0(@typescript-eslint/eslint-plugin@7.17.0)(@typescript-eslint/experimental-utils@5.62.0)(@typescript-eslint/parser@7.17.0)(eslint-config-prettier@9.1.0)(eslint-plugin-prettier@5.2.1)(eslint@8.57.0)(prettier@3.3.3) + version: 5.3.0(@typescript-eslint/eslint-plugin@7.17.0(@typescript-eslint/parser@7.17.0(eslint@8.57.0)(typescript@5.5.4))(eslint@8.57.0)(typescript@5.5.4))(@typescript-eslint/experimental-utils@5.62.0(eslint@8.57.0)(typescript@5.5.4))(@typescript-eslint/parser@7.17.0(eslint@8.57.0)(typescript@5.5.4))(eslint-config-prettier@9.1.0(eslint@8.57.0))(eslint-plugin-prettier@5.2.1(eslint-config-prettier@9.1.0(eslint@8.57.0))(eslint@8.57.0)(prettier@3.3.3))(eslint@8.57.0)(prettier@3.3.3) '@stacks/network': specifier: ^6.13.0 version: 6.16.0 @@ -36,7 +36,7 @@ importers: version: 6.2.2 '@typescript-eslint/eslint-plugin': specifier: ^7.5.0 - version: 7.17.0(@typescript-eslint/parser@7.17.0)(eslint@8.57.0)(typescript@5.5.4) + version: 7.17.0(@typescript-eslint/parser@7.17.0(eslint@8.57.0)(typescript@5.5.4))(eslint@8.57.0)(typescript@5.5.4) '@typescript-eslint/parser': specifier: ^7.5.0 version: 7.17.0(eslint@8.57.0)(typescript@5.5.4) @@ -51,16 +51,19 @@ importers: version: 9.1.0(eslint@8.57.0) eslint-plugin-prettier: specifier: ^5.1.3 - version: 5.2.1(eslint-config-prettier@9.1.0)(eslint@8.57.0)(prettier@3.3.3) + version: 5.2.1(eslint-config-prettier@9.1.0(eslint@8.57.0))(eslint@8.57.0)(prettier@3.3.3) prettier: specifier: ^3.2.5 version: 3.3.3 tsup: specifier: ^8.0.2 - version: 8.2.3(tsx@4.16.2)(typescript@5.5.4) + version: 8.2.3(postcss@8.4.40)(tsx@4.16.2)(typescript@5.5.4)(yaml@2.5.0) tsx: specifier: ^4.7.2 version: 4.16.2 + typedoc: + specifier: ^0.26.6 + version: 0.26.6(typescript@5.5.4) typescript: specifier: ^5.4.5 version: 5.5.4 @@ -69,7 +72,7 @@ importers: version: 2.18.4(typescript@5.5.4) vitest: specifier: ^1.4.0 - version: 1.6.0 + version: 1.6.0(@types/node@18.19.42) packages: @@ -588,6 +591,9 @@ packages: '@scure/btc-signer@1.3.2': resolution: {integrity: sha512-BmcQHvxaaShKwgbFC0vDk0xzqbMhNtNmgXm6u7cz07FNtGsVItUuHow6NbgHmc+oJSBZJRym5dz8+Uu0JoEJhQ==} + '@shikijs/core@1.14.1': + resolution: {integrity: sha512-KyHIIpKNaT20FtFPFjCQB5WVSTpLR/n+jQXhWHWVUMm9MaOaG9BGOG0MSyt7yA4+Lm+4c9rTc03tt3nYzeYSfw==} + '@sinclair/typebox@0.27.8': resolution: {integrity: sha512-+Fj43pSMwJs4KRrH/938Uf+uAELIgVBmQzg/q1YG10djyfA3TnrU8N8XzqCh/okZdszqBQTZf96idMfE5lnwTA==} @@ -612,6 +618,9 @@ packages: '@types/estree@1.0.5': resolution: {integrity: sha512-/kYRxGDLWzHOB7q+wtSUQlFrtcdUccpfy+X+9iMBpHK8QLLhx2wIPYuS5DYtR9Wa/YlZAbIovy7qVdB1Aq6Lyw==} + '@types/hast@3.0.4': + resolution: {integrity: sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==} + '@types/json-schema@7.0.15': resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==} @@ -621,6 +630,9 @@ packages: '@types/semver@7.5.8': resolution: {integrity: sha512-I8EUhyrgfLrcTkzV3TSsGyl1tSuPrEDzr0yd5m90UgNxQkyDXULk3b6MlQqTCpZpNtWe1K0hzclnZkTcLBe2UQ==} + '@types/unist@3.0.3': + resolution: {integrity: sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==} + '@typescript-eslint/eslint-plugin@7.17.0': resolution: {integrity: sha512-pyiDhEuLM3PuANxH7uNYan1AaFs5XE0zw1hq69JBvGvE7gSuEoQl1ydtEe/XQeoC3GQxLXyOVa5kNOATgM638A==} engines: {node: ^18.18.0 || >=20.0.0} @@ -940,6 +952,10 @@ packages: emoji-regex@9.2.2: resolution: {integrity: sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==} + entities@4.5.0: + resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==} + engines: {node: '>=0.12'} + esbuild@0.21.5: resolution: {integrity: sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==} engines: {node: '>=12'} @@ -1246,6 +1262,9 @@ packages: lines-and-columns@1.2.4: resolution: {integrity: sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==} + linkify-it@5.0.0: + resolution: {integrity: sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==} + load-tsconfig@0.2.5: resolution: {integrity: sha512-IXO6OCs9yg8tMKzfPZ1YmheJbZCiEsnBdcB03l0OcfK9prKnJb96siuHCr5Fl37/yo9DnKU+TLpxzTUspw9shg==} engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0} @@ -1276,9 +1295,19 @@ packages: lru-cache@10.4.3: resolution: {integrity: sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==} + lunr@2.3.9: + resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==} + magic-string@0.30.11: resolution: {integrity: sha512-+Wri9p0QHMy+545hKww7YAu5NyzF8iomPL/RQazugQ9+Ez4Ic3mERMd8ZTX5rfK944j+560ZJi8iAwgak1Ac7A==} + markdown-it@14.1.0: + resolution: {integrity: sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==} + hasBin: true + + mdurl@2.0.0: + resolution: {integrity: sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==} + merge-stream@2.0.0: resolution: {integrity: sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==} @@ -1482,6 +1511,10 @@ packages: proxy-from-env@1.1.0: resolution: {integrity: sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg==} + punycode.js@2.3.1: + resolution: {integrity: sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==} + engines: {node: '>=6'} + punycode@2.3.1: resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==} engines: {node: '>=6'} @@ -1541,6 +1574,9 @@ packages: resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==} engines: {node: '>=8'} + shiki@1.14.1: + resolution: {integrity: sha512-FujAN40NEejeXdzPt+3sZ3F2dx1U24BY2XTY01+MG8mbxCiA2XukXdcbyMyLAHJ/1AUUnQd1tZlvIjefWWEJeA==} + siginfo@2.0.0: resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==} @@ -1705,11 +1741,21 @@ packages: resolution: {integrity: sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==} engines: {node: '>=10'} + typedoc@0.26.6: + resolution: {integrity: sha512-SfEU3SH3wHNaxhFPjaZE2kNl/NFtLNW5c1oHsg7mti7GjmUj1Roq6osBQeMd+F4kL0BoRBBr8gQAuqBlfFu8LA==} + engines: {node: '>= 18'} + hasBin: true + peerDependencies: + typescript: 4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x + typescript@5.5.4: resolution: {integrity: sha512-Mtq29sKDAEYP7aljRgtPOpTvOfbwRWlS6dPRzwjdE+C0R4brX/GUyhHSecbHMFLNBLcJIPt9nl9yG5TZ1weH+Q==} engines: {node: '>=14.17'} hasBin: true + uc.micro@2.1.0: + resolution: {integrity: sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==} + ufo@1.5.4: resolution: {integrity: sha512-UsUk3byDzKd04EyoZ7U4DOlxQaD14JUKQl6/P7wiX4FNvUfm3XL246n9W5AmqwW5RSFJ27NAuM0iLscAOYUiGQ==} @@ -1841,6 +1887,11 @@ packages: resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==} engines: {node: '>=10'} + yaml@2.5.0: + resolution: {integrity: sha512-2wWLbGbYDiSqqIKoPjar3MPgB94ErzCtrNE1FdqGuaO0pi2JGjmE8aW8TDZwzU7vuxcGRdL/4gPQwQ7hD5AMSw==} + engines: {node: '>= 14'} + hasBin: true + yargs-parser@21.1.1: resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==} engines: {node: '>=12'} @@ -1868,14 +1919,15 @@ snapshots: optionalDependencies: '@scure/btc-signer': 1.3.2 - '@c4605/toolconfs@5.3.0(@typescript-eslint/eslint-plugin@7.17.0)(@typescript-eslint/experimental-utils@5.62.0)(@typescript-eslint/parser@7.17.0)(eslint-config-prettier@9.1.0)(eslint-plugin-prettier@5.2.1)(eslint@8.57.0)(prettier@3.3.3)': + '@c4605/toolconfs@5.3.0(@typescript-eslint/eslint-plugin@7.17.0(@typescript-eslint/parser@7.17.0(eslint@8.57.0)(typescript@5.5.4))(eslint@8.57.0)(typescript@5.5.4))(@typescript-eslint/experimental-utils@5.62.0(eslint@8.57.0)(typescript@5.5.4))(@typescript-eslint/parser@7.17.0(eslint@8.57.0)(typescript@5.5.4))(eslint-config-prettier@9.1.0(eslint@8.57.0))(eslint-plugin-prettier@5.2.1(eslint-config-prettier@9.1.0(eslint@8.57.0))(eslint@8.57.0)(prettier@3.3.3))(eslint@8.57.0)(prettier@3.3.3)': dependencies: - '@typescript-eslint/eslint-plugin': 7.17.0(@typescript-eslint/parser@7.17.0)(eslint@8.57.0)(typescript@5.5.4) '@typescript-eslint/experimental-utils': 5.62.0(eslint@8.57.0)(typescript@5.5.4) + optionalDependencies: + '@typescript-eslint/eslint-plugin': 7.17.0(@typescript-eslint/parser@7.17.0(eslint@8.57.0)(typescript@5.5.4))(eslint@8.57.0)(typescript@5.5.4) '@typescript-eslint/parser': 7.17.0(eslint@8.57.0)(typescript@5.5.4) eslint: 8.57.0 eslint-config-prettier: 9.1.0(eslint@8.57.0) - eslint-plugin-prettier: 5.2.1(eslint-config-prettier@9.1.0)(eslint@8.57.0)(prettier@3.3.3) + eslint-plugin-prettier: 5.2.1(eslint-config-prettier@9.1.0(eslint@8.57.0))(eslint@8.57.0)(prettier@3.3.3) prettier: 3.3.3 '@esbuild/aix-ppc64@0.21.5': @@ -2185,6 +2237,10 @@ snapshots: micro-packed: 0.6.3 optional: true + '@shikijs/core@1.14.1': + dependencies: + '@types/hast': 3.0.4 + '@sinclair/typebox@0.27.8': {} '@stacks/common@6.16.0': @@ -2220,6 +2276,10 @@ snapshots: '@types/estree@1.0.5': {} + '@types/hast@3.0.4': + dependencies: + '@types/unist': 3.0.3 + '@types/json-schema@7.0.15': {} '@types/node@18.19.42': @@ -2228,7 +2288,9 @@ snapshots: '@types/semver@7.5.8': {} - '@typescript-eslint/eslint-plugin@7.17.0(@typescript-eslint/parser@7.17.0)(eslint@8.57.0)(typescript@5.5.4)': + '@types/unist@3.0.3': {} + + '@typescript-eslint/eslint-plugin@7.17.0(@typescript-eslint/parser@7.17.0(eslint@8.57.0)(typescript@5.5.4))(eslint@8.57.0)(typescript@5.5.4)': dependencies: '@eslint-community/regexpp': 4.11.0 '@typescript-eslint/parser': 7.17.0(eslint@8.57.0)(typescript@5.5.4) @@ -2241,6 +2303,7 @@ snapshots: ignore: 5.3.1 natural-compare: 1.4.0 ts-api-utils: 1.3.0(typescript@5.5.4) + optionalDependencies: typescript: 5.5.4 transitivePeerDependencies: - supports-color @@ -2261,6 +2324,7 @@ snapshots: '@typescript-eslint/visitor-keys': 7.17.0 debug: 4.3.6 eslint: 8.57.0 + optionalDependencies: typescript: 5.5.4 transitivePeerDependencies: - supports-color @@ -2282,6 +2346,7 @@ snapshots: debug: 4.3.6 eslint: 8.57.0 ts-api-utils: 1.3.0(typescript@5.5.4) + optionalDependencies: typescript: 5.5.4 transitivePeerDependencies: - supports-color @@ -2299,6 +2364,7 @@ snapshots: is-glob: 4.0.3 semver: 7.6.3 tsutils: 3.21.0(typescript@5.5.4) + optionalDependencies: typescript: 5.5.4 transitivePeerDependencies: - supports-color @@ -2313,6 +2379,7 @@ snapshots: minimatch: 9.0.5 semver: 7.6.3 ts-api-utils: 1.3.0(typescript@5.5.4) + optionalDependencies: typescript: 5.5.4 transitivePeerDependencies: - supports-color @@ -2385,7 +2452,7 @@ snapshots: pretty-format: 29.7.0 abitype@1.0.5(typescript@5.5.4): - dependencies: + optionalDependencies: typescript: 5.5.4 acorn-jsx@5.3.2(acorn@8.12.1): @@ -2581,6 +2648,8 @@ snapshots: emoji-regex@9.2.2: {} + entities@4.5.0: {} + esbuild@0.21.5: optionalDependencies: '@esbuild/aix-ppc64': 0.21.5 @@ -2642,13 +2711,14 @@ snapshots: dependencies: eslint: 8.57.0 - eslint-plugin-prettier@5.2.1(eslint-config-prettier@9.1.0)(eslint@8.57.0)(prettier@3.3.3): + eslint-plugin-prettier@5.2.1(eslint-config-prettier@9.1.0(eslint@8.57.0))(eslint@8.57.0)(prettier@3.3.3): dependencies: eslint: 8.57.0 - eslint-config-prettier: 9.1.0(eslint@8.57.0) prettier: 3.3.3 prettier-linter-helpers: 1.0.0 synckit: 0.9.1 + optionalDependencies: + eslint-config-prettier: 9.1.0(eslint@8.57.0) eslint-scope@5.1.1: dependencies: @@ -2946,6 +3016,10 @@ snapshots: lines-and-columns@1.2.4: {} + linkify-it@5.0.0: + dependencies: + uc.micro: 2.1.0 + load-tsconfig@0.2.5: {} local-pkg@0.5.0: @@ -2971,10 +3045,23 @@ snapshots: lru-cache@10.4.3: {} + lunr@2.3.9: {} + magic-string@0.30.11: dependencies: '@jridgewell/sourcemap-codec': 1.5.0 + markdown-it@14.1.0: + dependencies: + argparse: 2.0.1 + entities: 4.5.0 + linkify-it: 5.0.0 + mdurl: 2.0.0 + punycode.js: 2.3.1 + uc.micro: 2.1.0 + + mdurl@2.0.0: {} + merge-stream@2.0.0: {} merge2@1.4.1: {} @@ -3114,10 +3201,13 @@ snapshots: mlly: 1.7.1 pathe: 1.1.2 - postcss-load-config@6.0.1(tsx@4.16.2): + postcss-load-config@6.0.1(postcss@8.4.40)(tsx@4.16.2)(yaml@2.5.0): dependencies: lilconfig: 3.1.2 + optionalDependencies: + postcss: 8.4.40 tsx: 4.16.2 + yaml: 2.5.0 postcss@8.4.40: dependencies: @@ -3141,6 +3231,8 @@ snapshots: proxy-from-env@1.1.0: {} + punycode.js@2.3.1: {} + punycode@2.3.1: {} queue-microtask@1.2.3: {} @@ -3199,6 +3291,11 @@ snapshots: shebang-regex@3.0.0: {} + shiki@1.14.1: + dependencies: + '@shikijs/core': 1.14.1 + '@types/hast': 3.0.4 + siginfo@2.0.0: {} signal-exit@3.0.7: {} @@ -3304,7 +3401,7 @@ snapshots: tslib@2.6.3: {} - tsup@8.2.3(tsx@4.16.2)(typescript@5.5.4): + tsup@8.2.3(postcss@8.4.40)(tsx@4.16.2)(typescript@5.5.4)(yaml@2.5.0): dependencies: bundle-require: 5.0.0(esbuild@0.23.0) cac: 6.7.14 @@ -3316,12 +3413,14 @@ snapshots: globby: 11.1.0 joycon: 3.1.1 picocolors: 1.0.1 - postcss-load-config: 6.0.1(tsx@4.16.2) + postcss-load-config: 6.0.1(postcss@8.4.40)(tsx@4.16.2)(yaml@2.5.0) resolve-from: 5.0.0 rollup: 4.19.1 source-map: 0.8.0-beta.0 sucrase: 3.35.0 tree-kill: 1.2.2 + optionalDependencies: + postcss: 8.4.40 typescript: 5.5.4 transitivePeerDependencies: - jiti @@ -3349,8 +3448,19 @@ snapshots: type-fest@0.20.2: {} + typedoc@0.26.6(typescript@5.5.4): + dependencies: + lunr: 2.3.9 + markdown-it: 14.1.0 + minimatch: 9.0.5 + shiki: 1.14.1 + typescript: 5.5.4 + yaml: 2.5.0 + typescript@5.5.4: {} + uc.micro@2.1.0: {} + ufo@1.5.4: {} undici-types@5.26.5: {} @@ -3368,21 +3478,22 @@ snapshots: '@scure/bip39': 1.3.0 abitype: 1.0.5(typescript@5.5.4) isows: 1.0.4(ws@8.17.1) - typescript: 5.5.4 webauthn-p256: 0.0.5 ws: 8.17.1 + optionalDependencies: + typescript: 5.5.4 transitivePeerDependencies: - bufferutil - utf-8-validate - zod - vite-node@1.6.0: + vite-node@1.6.0(@types/node@18.19.42): dependencies: cac: 6.7.14 debug: 4.3.6 pathe: 1.1.2 picocolors: 1.0.1 - vite: 5.3.5 + vite: 5.3.5(@types/node@18.19.42) transitivePeerDependencies: - '@types/node' - less @@ -3393,15 +3504,16 @@ snapshots: - supports-color - terser - vite@5.3.5: + vite@5.3.5(@types/node@18.19.42): dependencies: esbuild: 0.21.5 postcss: 8.4.40 rollup: 4.19.1 optionalDependencies: + '@types/node': 18.19.42 fsevents: 2.3.3 - vitest@1.6.0: + vitest@1.6.0(@types/node@18.19.42): dependencies: '@vitest/expect': 1.6.0 '@vitest/runner': 1.6.0 @@ -3420,9 +3532,11 @@ snapshots: strip-literal: 2.1.0 tinybench: 2.8.0 tinypool: 0.8.4 - vite: 5.3.5 - vite-node: 1.6.0 + vite: 5.3.5(@types/node@18.19.42) + vite-node: 1.6.0(@types/node@18.19.42) why-is-node-running: 2.3.0 + optionalDependencies: + '@types/node': 18.19.42 transitivePeerDependencies: - less - lightningcss @@ -3481,6 +3595,8 @@ snapshots: y18n@5.0.8: {} + yaml@2.5.0: {} + yargs-parser@21.1.1: {} yargs@17.7.2: From 0fce3063d14910cd8b11d76794beaeb0221429ab Mon Sep 17 00:00:00 2001 From: david weil Date: Mon, 26 Aug 2024 12:44:28 -0300 Subject: [PATCH 4/7] update package json --- package.json | 1 + 1 file changed, 1 insertion(+) diff --git a/package.json b/package.json index e534963..4cebcfb 100644 --- a/package.json +++ b/package.json @@ -34,6 +34,7 @@ "scripts": { "gen:stacksContract": "rm -rf generated/smartContract && mkdir -p generated/smartContract && tsx ./scripts/generateClarityTranscoders.ts", "gen": "pnpm run gen:stacksContract", + "docs": "npx typedoc src/index.ts", "build": "pnpm run gen && rm -rf lib && tsup-node --sourcemap --dts -d lib --format cjs,esm src", "prepare": "pnpm run build", "test": "vitest --exclude lib" From 5ef309db9273a2d866c8025f96388217aa276c61 Mon Sep 17 00:00:00 2001 From: "ignacio.pena@coinfabrik.com" Date: Mon, 26 Aug 2024 16:18:47 -0300 Subject: [PATCH 5/7] add errors to typedoc --- src/utils/errors.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/utils/errors.ts b/src/utils/errors.ts index 650d863..6680b3b 100644 --- a/src/utils/errors.ts +++ b/src/utils/errors.ts @@ -1,5 +1,6 @@ import { ChainId, TokenId } from "../xlinkSdkUtils/types" +/** Extends the Error class and serves as the base for all custom errors within the SDK. */ export class XLinkSDKErrorBase extends Error { constructor(...args: ConstructorParameters) { super(...args) @@ -7,6 +8,7 @@ export class XLinkSDKErrorBase extends Error { } } +/** It is thrown when a method in the SDK receives invalid parameters. */ export class InvalidMethodParametersError extends XLinkSDKErrorBase { constructor( public methodPath: string[], @@ -21,6 +23,7 @@ export class InvalidMethodParametersError extends XLinkSDKErrorBase { } } +/** It is thrown when an attempt is made to bridge tokens between unsupported chains in the SDK. */ export class UnsupportedBridgeRouteError extends XLinkSDKErrorBase { constructor( public fromChain: ChainId, @@ -35,12 +38,14 @@ export class UnsupportedBridgeRouteError extends XLinkSDKErrorBase { } } +/** It is thrown when a method in the SDK receives an unknown chain. */ export class UnsupportedChainError extends XLinkSDKErrorBase { constructor(public chain: ChainId) { super(`Unsupported chain: ${chain}`) this.name = "UnsupportedChainError" } } +/** It is thrown when a smart contract is assigned an unknown or unsupported chain ID. */ export class UnsupportedContractAssignedChainIdError extends XLinkSDKErrorBase { constructor(public chainId: bigint) { super(`Unsupported smart contract assigned chain id: ${chainId}`) From cf4de645074c7f5f9c10554d08e1b6081b8025f5 Mon Sep 17 00:00:00 2001 From: "ignacio.pena@coinfabrik.com" Date: Tue, 27 Aug 2024 18:18:59 -0300 Subject: [PATCH 6/7] add use cases and missing function to typedoc --- README.md | 179 ++++++++++++++++++++++++++++++++++++++++++++++++ src/XLinkSDK.ts | 34 ++++++--- 2 files changed, 205 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index d48d721..51e6c8e 100644 --- a/README.md +++ b/README.md @@ -217,3 +217,182 @@ Possible exceptions: None. The function returns `undefined` if the chainId or ad - `UnsupportedChainError`: It is thrown when a method in the SDK receives an unknown chain. - `UnsupportedContractAssignedChainIdError`: It is thrown when a smart contract is assigned an unknown or unsupported chain ID. - `XLinkSDKErrorBase`: Extends the Error class and serves as the base for all custom errors within the SDK. + +### USE CASES + +Create an instance of the SDK with default options +```typescript +const xlinkSdk = new XLinkSDK(); +``` +#### Available Methods: +1. `getSupportedRoutes()` +```typescript +const routes = await xlinkSdk.getSupportedRoutes({ + fromChain: "evm-ethereum", + toChain: "stacks-mainnet", + fromToken: "evm-usdt", + toToken: "stx-susdt", +}); +``` + +2. `bridgeInfoFromStacks()` +```typescript +const bridgeInfo = await xlinkSdk.bridgeInfoFromStacks({ + fromChain: "stacks-mainnet", + toChain: "evm-ethereum", + fromToken: "stx-susdt", + toToken: "evm-usdt", + amount: 100, +}); +console.log("Bridge Info:", bridgeInfo); +``` + +3. `bridgeFromStacks()` +```typescript +const result = await xlinkSdk.bridgeFromStacks({ + fromChain: "stacks-mainnet", + toChain: "evm-ethereum", + fromToken: "stx-susdt", + toToken: "evm-usdt", + toAddress: "0x...", + amount: 10, + sendTransaction: async (tx: ContractCallOptions) => Promise<{txid: string}> { + // this implementation is for use the bridge from Stacks mainnet network.. + // you need to have one implementation for each different network + // also this is fixed to use node-library and you'll need the user key + const network = StacksMainnet(); + const transaction = await makeContractCall({ + contractAddress: options.contractAddress, + contractName: options.contractName, + functionName: options.functionName, + functionArgs: options.functionArgs, + // this not required if sendTransaction is from a wallet, but required when using from node + senderKey: /* here we need to pass the sender address private key in order to sign the transaction */ + //validateWithAbi: true, + network, + postConditions: options.postConditions, + anchorMode: options.anchorMode, + }); + const broadcastResponse = await broadcastTransaction(transaction, network); + return broadcastResponse.txid; + } +}); +console.log("Transaction ID:", result.txid); +``` + +4. `getEVMContractAddress()` +```typescript +const contractAddress = await xlinkSdk.getEVMContractAddress( + "evm-bsc", + "BridgeEndpoint" +); +console.log("Contract Address:", contractAddress); +``` + +5. `evmAddressFromEVMToken()` +```typescript +const address = await xlinkSdk.evmAddressFromEVMToken( + "evm-ethereum", + "evm-usdt" +); +console.log("EVM Address:", address); +``` + +6. `evmAddressToEVMToken()` +```typescript +const tokenId = await xlinkSdk.evmAddressToEVMToken( + "evm-coredao", + "0x..." +); +console.log("Token ID:", tokenId); +``` + +7. `bridgeInfoFromEVM()` +```typescript +const bridgeInfo = await xlinkSdk.bridgeInfoFromEVM({ + fromChain: "evm-ethereum", + toChain: "stacks-mainnet", + fromToken: "evm-usdt", + toToken: "stx-susdt", + amount: 100, +}); +console.log("Bridge Info:", bridgeInfo); +``` +8. `bridgeFromEVM()` +```typescript +const result = await xlinkSdk.bridgeFromEVM({ + fromChain: "evm-ethereum", + toChain: "stacks-mainnet", + fromToken: "evm-usdt", + toToken: "stx-susdt", + toAddress: "0x...", + amount: 10, + sendTransaction: // TODO +}); +console.log("Transaction ID:", result.txHash); +``` + +9. `getTimeLockedAssetsFromEVM()` +```typescript +const timeLockedAssets = await xlinkSdk.getTimeLockedAssetsFromEVM({ + walletAddress: "0x...", + chains: ["evm-bitlayer", "evm-lorenzo"], +}); +console.log("Time-Locked Assets:", timeLockedAssets); +``` + +10. `claimTimeLockedAssetsFromEVM()` +```typescript +const claimResult = await xlinkSdk.claimTimeLockedAssetsFromEVM({ + chain: "evm-ethereum", + lockedAssetIds: ["asset-id-1", "asset-id-2"], + sendTransaction: // TODO +}); +console.log("Claim Transaction Hash:", claimResult?.txHash); +``` + +11. `bridgeInfoFromBitcoin()` +```typescript +const bridgeInfo = await xlinkSdk.bridgeInfoFromBitcoin({ + fromChain: "bitcoin-mainnet", + toChain: "evm-ethereum", + amount: 1, +}); +console.log("Bridge Info:", bridgeInfo); +``` + +12. `estimateBridgeTransactionFromBitcoin()` +```typescript +const estimate = await xlinkSdk.estimateBridgeTransactionFromBitcoin({ + fromChain: "bitcoin-mainnet", + toChain: "evm-ethereum", + fromToken: "btc-btc", + toToken: "evm-wbtc", + fromAddress: "bitcoin address", + fromAddressScriptPubKey: scriptPubKey, + toAddress: "0x...", + amount: 1, + networkFeeRate: 10n, + reselectSpendableUTXOs: // TODO +}); +console.log("Estimated Fee:", estimate.fee); +console.log("Estimated vSize:", estimate.estimatedVSize); +``` + +13. `bridgeFromBitcoin()` +```typescript +const result = await xlinkSdk.bridgeFromBitcoin({ + fromChain: "bitcoin-mainnet", + toChain: "evm-ethereum", + fromToken: "btc-btc", + toToken: "evm-wbtc", + fromAddress: "bitcoin address", + fromAddressScriptPubKey: scriptPubKey, + toAddress: "0x...", + amount: 1, + networkFeeRate: 10n, + reselectSpendableUTXOs: // TODO + signPsbt: // TODO +}); +console.log("Transaction ID:", result.tx); +``` \ No newline at end of file diff --git a/src/XLinkSDK.ts b/src/XLinkSDK.ts index 5519c1d..f85219f 100644 --- a/src/XLinkSDK.ts +++ b/src/XLinkSDK.ts @@ -198,8 +198,6 @@ export class XLinkSDK { * - `fromAmount: SDKNumber` - The amount of tokens being transferred. * - `toAmount: SDKNumber` - The amount of tokens expected on the destination chain after the transfer. * - `feeAmount: SDKNumber` - The fee amount deducted during the transfer. - * - `transferProphets: PublicTransferProphet[]` - An array of objects containing additional details about the transfer, - * such as fees, minimum and maximum bridge amounts, and whether the transfer route is paused. * @throws UnsupportedBridgeRouteError - If the provided route between the source and destination * chains or tokens is unsupported. */ @@ -220,7 +218,7 @@ export class XLinkSDK { * - `toToken: TokenId` - The token expected on the destination chain. * - `toAddress: string` - The recipient's address on the destination blockchain. * - `amount: SDKNumber` - The amount of tokens to transfer. - * - `sendTransaction: TODO. + * - `sendTransaction: // TODO. * * @returns A promise that resolves with the transaction ID (`txid`) of the bridging operation. * @throws UnsupportedBridgeRouteError - If the provided route between the source and destination @@ -288,6 +286,28 @@ export class XLinkSDK { return getEVMToken(this.sdkContext, chain, address) } + /** + * This function provides detailed information about token transfers from an EVM-compatible blockchain to other supported + * blockchain networks, including Stacks, Bitcoin, and other EVM-compatible chains. It verifies the validity of the transfer + * route and retrieves bridge information based on the destination chain and tokens. + * @param input - An object containing the input parameters required for retrieving bridge information: + * - `fromChain: ChainId` - The ID of the source blockchain (Stacks in this case). + * - `toChain: ChainId` - The ID of the destination blockchain (Bitcoin, EVM-compatible chains, etc.). + * - `fromToken: TokenId` - The token being transferred from the Stacks network. + * - `toToken: TokenId` - The token expected on the destination chain. + * - `amount: SDKNumber` - The amount of tokens involved in the transfer. + * + * @returns A promise that resolves with an object containing detailed information about the token transfer, including: + * - `fromChain: KnownChainId.KnownChain` - The source blockchain. + * - `fromToken: KnownTokenId.KnownToken` - The token being transferred from the Stacks network. + * - `toChain: KnownChainId.KnownChain` - The destination blockchain. + * - `toToken: KnownTokenId.KnownToken` - The token expected on the destination chain. + * - `fromAmount: SDKNumber` - The amount of tokens being transferred. + * - `toAmount: SDKNumber` - The amount of tokens expected on the destination chain after the transfer. + * - `feeAmount: SDKNumber` - The fee amount deducted during the transfer. + * @throws UnsupportedBridgeRouteError - If the provided route between the source and destination + * chains or tokens is unsupported. + */ bridgeInfoFromEVM( input: BridgeInfoFromEVMInput, ): Promise { @@ -306,7 +326,7 @@ export class XLinkSDK { * - `toAddress: string` - The recipient's address on the destination blockchain. * - `toAddressScriptPubKey?: Uint8Array` - The script public key for the `toAddress`, required when the destination is a Bitcoin chain. * - `amount: SDKNumber` - The amount of tokens to transfer. - * - `sendTransaction: TODO. + * - `sendTransaction: // TODO. * * @returns A promise that resolves with the transaction hash (`txHash`) of the bridging operation. * @throws UnsupportedBridgeRouteError - If the provided route between the source and destination @@ -346,7 +366,7 @@ export class XLinkSDK { * @param input - An object containing the input parameters required for claiming time-locked assets: * - `chain: KnownChainId.EVMChain` - The ID of the EVM-compatible blockchain where the assets are locked. * - `lockedAssetIds: string[]` - An array of IDs representing the locked assets to be claimed. - * - `sendTransaction: TODO. + * - `sendTransaction: // TODO. * * @returns A promise that resolves with the transaction hash (`txHash`) of the claiming operation, or `undefined` if the operation fails. * @throws UnsupportedChainError - If the provided EVM chain is unsupported or invalid. @@ -383,8 +403,6 @@ export class XLinkSDK { * - `fromAmount: SDKNumber` - The amount of tokens being transferred. * - `toAmount: SDKNumber` - The amount of tokens expected on the destination chain after the transfer. * - `feeAmount: SDKNumber` - The fee amount deducted during the transfer. - * - `transferProphets: PublicTransferProphet[]` - An array of objects containing additional details about the transfer, - * such as fees, minimum and maximum bridge amounts, and whether the transfer route is paused. * @throws UnsupportedBridgeRouteError - If the provided route between the source and destination * chains is unsupported. */ @@ -403,7 +421,7 @@ export class XLinkSDK { * - `toAddress: string` - The destination address on the target blockchain. * - `amount: SDKNumber` - The amount of tokens to be transferred. * - `networkFeeRate: bigint` - The fee rate for the Bitcoin network. - * - `reselectSpendableUTXOs: ReselectSpendableUTXOsFn` - A function to reselect the spendable UTXOs. + * - `reselectSpendableUTXOs: // TODO. * * @returns A promise that resolves with an object containing the estimated transaction details: * - `fee: SDKNumber` - The estimated transaction fee. From c1c75b9388405be536f385ed129a4999239940b1 Mon Sep 17 00:00:00 2001 From: "ignacio.pena@coinfabrik.com" Date: Wed, 28 Aug 2024 17:39:18 -0300 Subject: [PATCH 7/7] README refactor and link to typedoc for documentation --- README.md | 353 +++++++++++------------------------------------------- 1 file changed, 69 insertions(+), 284 deletions(-) diff --git a/README.md b/README.md index 51e6c8e..a4118e7 100644 --- a/README.md +++ b/README.md @@ -60,339 +60,124 @@ Note: Users can transfer between different coins/tokens, not just the same token ### XLink SDK - The `XLinkSDK` object contains the most important functions of this library, all grouped together. To create it: ```typescript const theSdk = new XLinkSDK(); ``` -These functions are part of the `XLinkSDK` object: +For detailed API documentation, including a full list of available methods and their usage, please refer to: -#### bridgeFromBitcoin - -This function facilitates the transfer of tokens from the Bitcoin network to other supported blockchain networks. It checks the validity of the route and then calls the appropriate bridging function based on the destination chain. - -```typescript -bridgeFromBitcoin(input: BridgeFromBitcoinInput): Promise -``` - -Possible exceptions: `UnsupportedBridgeRouteError`. - -#### bridgeFromEVM - -This function facilitates the transfer of tokens from an EVM-compatible blockchain to other supported blockchain networks, including Stacks, Bitcoin, and other EVM-compatible chains. It validates the route and calls the appropriate bridging function based on the destination chain and tokens involved. -```typescript -bridgeFromEVM(input: BridgeFromEVMInput): Promise -``` -Possible exceptions: `UnsupportedBridgeRouteError`. - -#### bridgeFromStacks -This function facilitates the transfer of tokens from the Stacks network to other supported blockchain networks, including Bitcoin and EVM-compatible chains. It validates the route and calls the appropriate bridging function based on the destination chain and tokens involved. -```typescript -bridgeFromStacks(input: BridgeFromStacksInput): Promise -``` -Possible exceptions: `UnsupportedBridgeRouteError`. - -#### bridgeInfoFromBitcoin - -This function provides detailed information about token transfers from the Bitcoin network to other supported blockchain networks, including Stacks and EVM-compatible chains. It verifies the validity of the transfer route and retrieves bridge information based on the destination chain. - -```typescript -const bridgeInfoFromBitcoin = async (info: BridgeInfoFromBitcoinInput): Promise -``` -Possible exceptions: `UnsupportedBridgeRouteError`. - -#### bridgeInfoFromEVM - -This function provides detailed information about token transfers from an EVM-compatible blockchain to other supported blockchain networks, including Stacks, Bitcoin, and other EVM-compatible chains. It verifies the validity of the transfer route and retrieves bridge information based on the destination chain and tokens. - -```typescript -bridgeInfoFromEVM(input: BridgeInfoFromEVMInput): Promise -``` -Possible exceptions: `UnsupportedBridgeRouteError`. - -#### bridgeInfoFromStacks - -This function provides detailed information about token transfers from the Stacks network to other supported blockchain networks, including Bitcoin and EVM-compatible chains. It verifies the validity of the transfer route and retrieves bridge information based on the destination chain and tokens. - -```typescript -bridgeInfoFromStacks(input: BridgeInfoFromStacksInput): Promise -``` -Possible exceptions: `UnsupportedBridgeRouteError`. - -#### claimTimeLockedAssetsFromEVM - -This function facilitates the claiming of time-locked assets on EVM-compatible chains. It uses smart contract functions to execute the release of locked assets based on predefined conditions. - -```typescript -claimTimeLockedAssetsFromEVM(input: ClaimTimeLockedAssetsInput): Promise -``` - -Possible exceptions: `UnsupportedChainError`. - -#### getTimeLockedAssetsFromEVM - -This function retrieves a list of time-locked assets for a given wallet address across multiple EVM-compatible blockchain networks. It queries smart contracts to find and return information about the assets that are currently locked in time-based agreements. - -```typescript -getTimeLockedAssetsFromEVM(input: GetTimeLockedAssetsInput): Promise -``` - -Possible exceptions: `UnsupportedChainError`. - -#### estimateBridgeTransactionFromBitcoin - -This function estimates the transaction fee and vSize for move or swap tokens from the Bitcoin network to other supported blockchain networks, including Stacks and EVM-compatible chains. -```typescript -estimateBridgeTransactionFromBitcoin(input: EstimateBridgeTransactionFromBitcoinInput): Promise -``` - -Possible exceptions: `UnsupportedBridgeRouteError` - -#### evmAddressFromEVMToken - -This function retrieves the contract address of a specific token on a given EVM-compatible blockchain. - -```typescript -async evmAddressFromEVMToken(chain: ChainId, token: KnownTokenId.EVMToken): Promise -``` - -Possible exceptions: None. The function returns `undefined` if the chain is not EVM-compatible or if the contract address cannot be retrieved. - -#### evmAddressToEVMToken - -This function maps a given contract address on an EVM-compatible blockchain to its corresponding known token ID. - -```typescript -async evmAddressToEVMToken(chain: ChainId, address: EVMAddress): Promise -``` - -Possible exceptions: None. The function returns `undefined` if the chain is not EVM-compatible or if the address cannot be matched. - -#### getEVMContractAddress - -This function retrieves the contract address of a specific type of contract (e.g., a bridge endpoint) on a given EVM-compatible blockchain. - -```typescript -async getEVMContractAddress(chain: ChainId, contractType: PublicEVMContractType): Promise -``` - -Possible exceptions: None. The function returns `undefined` if the chain is not EVM-compatible or if the address cannot be matched. - -#### getSupportedRoutes - -This function retrieves the list of supported routes for token transfers between blockchain networks, filtered based on optional conditions. It aggregates the results from different blockchain networks (Stacks, EVM, Bitcoin) to return a list of possible routes. - -```typescript -async getSupportedRoutes(conditions?: GetSupportedRoutesFn_Conditions): Promise -``` - -Possible exceptions: None. - -#### stacksAddressFromStacksToken - -This function retrieves the contract address associated with a specific token on the Stacks blockchain. - -```typescript -async function stacksAddressFromStacksToken(chain: ChainId, token: KnownTokenId.StacksToken): Promise -``` -Possible exceptions: None. The function returns `undefined` if the chainId or token is not valid. - -#### stacksAddressToStacksToken - -This function maps a given Stacks contract address to its corresponding known token ID. - -```typescript -async function stacksAddressToStacksToken(chain: ChainId, address: StacksContractAddress): Promise -``` - -Possible exceptions: None. The function returns `undefined` if the chainId or address is not valid. - - -### Errors - -- `InvalidMethodParametersError`: It is thrown when a method in the SDK receives invalid parameters. -- `UnsupportedBridgeRouteError`: It is thrown when an attempt is made to bridge tokens between unsupported chains in the SDK. -- `UnsupportedChainError`: It is thrown when a method in the SDK receives an unknown chain. -- `UnsupportedContractAssignedChainIdError`: It is thrown when a smart contract is assigned an unknown or unsupported chain ID. -- `XLinkSDKErrorBase`: Extends the Error class and serves as the base for all custom errors within the SDK. +[SDK API Documentation](https://docs-typedoc.xlink-sdk.pages.dev/classes/XLinkSDK.XLinkSDK) ### USE CASES Create an instance of the SDK with default options ```typescript +import{ XLinkSDK } from '@xlink-project/xlink-sdk/src'; + const xlinkSdk = new XLinkSDK(); ``` -#### Available Methods: -1. `getSupportedRoutes()` +1. Bridge from Stacks ```typescript -const routes = await xlinkSdk.getSupportedRoutes({ - fromChain: "evm-ethereum", - toChain: "stacks-mainnet", - fromToken: "evm-usdt", - toToken: "stx-susdt", -}); -``` +import { BridgeInfoFromStacksInput } from '@xlink-project/xlink-sdk/src/xlinkSdkUtils/bridgeInfoFromStacks'; +import { BridgeFromStacksInput } from '@xlink-project/xlink-sdk/src/xlinkSdkUtils/bridgeFromStacks'; +import { KnownChainId, KnownTokenId } from '@xlink-project/xlink-sdk/src/utils/types/knownIds'; -2. `bridgeInfoFromStacks()` -```typescript +// Get bridge info const bridgeInfo = await xlinkSdk.bridgeInfoFromStacks({ - fromChain: "stacks-mainnet", - toChain: "evm-ethereum", - fromToken: "stx-susdt", - toToken: "evm-usdt", + fromChain: KnownChainId.Stacks.Mainnet, + toChain: KnownChainId.EVM.Ethereum, + fromToken: KnownTokenId.Stacks.sUSDT, + toToken: KnownTokenId.EVM.USDT, amount: 100, -}); +} as BridgeInfoFromStacksInput); console.log("Bridge Info:", bridgeInfo); -``` -3. `bridgeFromStacks()` -```typescript +// Perform the bridge operation const result = await xlinkSdk.bridgeFromStacks({ - fromChain: "stacks-mainnet", - toChain: "evm-ethereum", - fromToken: "stx-susdt", - toToken: "evm-usdt", + fromChain: KnownChainId.Stacks.Mainnet, + toChain: KnownChainId.EVM.Ethereum, + fromToken: KnownTokenId.Stacks.sUSDT, + toToken: KnownTokenId.EVM.USDT, toAddress: "0x...", amount: 10, - sendTransaction: async (tx: ContractCallOptions) => Promise<{txid: string}> { - // this implementation is for use the bridge from Stacks mainnet network.. - // you need to have one implementation for each different network - // also this is fixed to use node-library and you'll need the user key - const network = StacksMainnet(); - const transaction = await makeContractCall({ - contractAddress: options.contractAddress, - contractName: options.contractName, - functionName: options.functionName, - functionArgs: options.functionArgs, - // this not required if sendTransaction is from a wallet, but required when using from node - senderKey: /* here we need to pass the sender address private key in order to sign the transaction */ - //validateWithAbi: true, - network, - postConditions: options.postConditions, - anchorMode: options.anchorMode, - }); - const broadcastResponse = await broadcastTransaction(transaction, network); - return broadcastResponse.txid; + sendTransaction: async (tx: ContractCallOptions) => { + // Implementation for sending transaction from Stacks mainnet + const network = new StacksMainnet(); + const transaction = await makeContractCall({ + contractAddress: tx.contractAddress, + contractName: tx.contractName, + functionName: tx.functionName, + functionArgs: tx.functionArgs, + senderKey: /* sender address private key */, + network, + postConditions: tx.postConditions, + anchorMode: tx.anchorMode, + }); + const broadcastResponse = await broadcastTransaction(transaction, network); + return broadcastResponse.txid; } -}); +} as BridgeFromStacksInput); console.log("Transaction ID:", result.txid); ``` -4. `getEVMContractAddress()` +2. Bridge from EVM ```typescript -const contractAddress = await xlinkSdk.getEVMContractAddress( - "evm-bsc", - "BridgeEndpoint" -); -console.log("Contract Address:", contractAddress); -``` +import { BridgeInfoFromEVMInput } from '@xlink-project/xlink-sdk/src/xlinkSdkUtils/bridgeInfoFromEVM'; +import { BridgeFromEVMInput } from '@xlink-project/xlink-sdk/src/xlinkSdkUtils/bridgeFromEVM'; +import { KnownChainId, KnownTokenId } from '@xlink-project/xlink-sdk/src/utils/types/knownIds'; -5. `evmAddressFromEVMToken()` -```typescript -const address = await xlinkSdk.evmAddressFromEVMToken( - "evm-ethereum", - "evm-usdt" -); -console.log("EVM Address:", address); -``` - -6. `evmAddressToEVMToken()` -```typescript -const tokenId = await xlinkSdk.evmAddressToEVMToken( - "evm-coredao", - "0x..." -); -console.log("Token ID:", tokenId); -``` - -7. `bridgeInfoFromEVM()` -```typescript +// Get bridge info const bridgeInfo = await xlinkSdk.bridgeInfoFromEVM({ - fromChain: "evm-ethereum", - toChain: "stacks-mainnet", - fromToken: "evm-usdt", - toToken: "stx-susdt", + fromChain: KnownChainId.EVM.Ethereum, + toChain: KnownChainId.Stacks.Mainnet, + fromToken: KnownTokenId.EVM.USDT, + toToken: KnownTokenId.Stacks.sUSDT, amount: 100, -}); +} as BridgeInfoFromEVMInput); console.log("Bridge Info:", bridgeInfo); -``` -8. `bridgeFromEVM()` -```typescript + +// Perform the bridge operation const result = await xlinkSdk.bridgeFromEVM({ - fromChain: "evm-ethereum", - toChain: "stacks-mainnet", - fromToken: "evm-usdt", - toToken: "stx-susdt", + fromChain: KnownChainId.EVM.Ethereum, + toChain: KnownChainId.Stacks.Mainnet, + fromToken: KnownTokenId.EVM.USDT, + toToken: KnownTokenId.Stacks.sUSDT, toAddress: "0x...", amount: 10, - sendTransaction: // TODO -}); + sendTransaction: // Implementation for sending transaction from EVM chain +} as BridgeFromEVMInput); console.log("Transaction ID:", result.txHash); ``` -9. `getTimeLockedAssetsFromEVM()` +3. Bridge from Bitcoin ```typescript -const timeLockedAssets = await xlinkSdk.getTimeLockedAssetsFromEVM({ - walletAddress: "0x...", - chains: ["evm-bitlayer", "evm-lorenzo"], -}); -console.log("Time-Locked Assets:", timeLockedAssets); -``` +import { BridgeInfoFromBitcoinInput } from '@xlink-project/xlink-sdk/src/xlinkSdkUtils/bridgeInfoFromBitcoin'; +import { BridgeFromBitcoinInput } from '@xlink-project/xlink-sdk/src/xlinkSdkUtils/bridgeFromBitcoin'; +import { KnownChainId, KnownTokenId } from '@xlink-project/xlink-sdk/src/utils/types/knownIds'; -10. `claimTimeLockedAssetsFromEVM()` -```typescript -const claimResult = await xlinkSdk.claimTimeLockedAssetsFromEVM({ - chain: "evm-ethereum", - lockedAssetIds: ["asset-id-1", "asset-id-2"], - sendTransaction: // TODO -}); -console.log("Claim Transaction Hash:", claimResult?.txHash); -``` - -11. `bridgeInfoFromBitcoin()` -```typescript +// Get bridge info const bridgeInfo = await xlinkSdk.bridgeInfoFromBitcoin({ - fromChain: "bitcoin-mainnet", - toChain: "evm-ethereum", + fromChain: KnownChainId.Bitcoin.Mainnet, + toChain: KnownChainId.EVM.Ethereum, amount: 1, -}); +} as BridgeInfoFromBitcoinInput); console.log("Bridge Info:", bridgeInfo); -``` -12. `estimateBridgeTransactionFromBitcoin()` -```typescript -const estimate = await xlinkSdk.estimateBridgeTransactionFromBitcoin({ - fromChain: "bitcoin-mainnet", - toChain: "evm-ethereum", - fromToken: "btc-btc", - toToken: "evm-wbtc", - fromAddress: "bitcoin address", - fromAddressScriptPubKey: scriptPubKey, - toAddress: "0x...", - amount: 1, - networkFeeRate: 10n, - reselectSpendableUTXOs: // TODO -}); -console.log("Estimated Fee:", estimate.fee); -console.log("Estimated vSize:", estimate.estimatedVSize); -``` - -13. `bridgeFromBitcoin()` -```typescript +// Perform the bridge operation const result = await xlinkSdk.bridgeFromBitcoin({ - fromChain: "bitcoin-mainnet", - toChain: "evm-ethereum", - fromToken: "btc-btc", - toToken: "evm-wbtc", + fromChain: KnownChainId.Bitcoin.Mainnet, + toChain: KnownChainId.EVM.Ethereum, + fromToken: KnownTokenId.Bitcoin.BTC, + toToken: KnownTokenId.EVM.WBTC, fromAddress: "bitcoin address", fromAddressScriptPubKey: scriptPubKey, toAddress: "0x...", amount: 1, networkFeeRate: 10n, - reselectSpendableUTXOs: // TODO - signPsbt: // TODO -}); + reselectSpendableUTXOs: // Implementation for reselect UTXOs + signPsbt: // Implementation for signing PSBT +} as BridgeFromBitcoinInput); console.log("Transaction ID:", result.tx); ``` \ No newline at end of file