@avalabs/bridge-unified - npm Package Compare versions

Comparing version 0.0.0-feat-unified-api-interface-20231213185352 to 0.0.0-feat-unified-api-interface-20231214161604

CHANGELOG.md

 # @avalabs/unified-bridge
 
-## 0.0.0-feat-unified-api-interface-20231213185352
+## 0.0.0-feat-unified-api-interface-20231214161604
 
@@ -5,0 +5,0 @@ ### Major Changes

dist/index.d.ts

@@ -120,3 +120,3 @@ import { Address, TransactionRequest, Hex } from 'viem';
     trackTransfer: (transfer: TrackingParams) => {
-        cancel?: () => void;
+        cancel: () => void;
         result: Promise<BridgeTransfer>;
@@ -154,3 +154,3 @@ };
     trackTransfer: (params: TrackingParams) => {
-        cancel?: (() => void) | undefined;
+        cancel: () => void;
         result: Promise<BridgeTransfer>;
@@ -157,0 +157,0 @@ };

package.json

 {
   "name": "@avalabs/bridge-unified",
-  "version": "0.0.0-feat-unified-api-interface-20231213185352",
+  "version": "0.0.0-feat-unified-api-interface-20231214161604",
   "main": "dist/index.js",
@@ -18,3 +18,3 @@ "type": "module",
     "@internal/tsup-config": "0.0.1",
-    "eslint-config-custom": "0.0.0-feat-unified-api-interface-20231213185352"
+    "eslint-config-custom": "0.0.0-feat-unified-api-interface-20231214161604"
   },
@@ -21,0 +21,0 @@ "scripts": {

README.md

@@ -19,7 +19,7 @@ <p align="center">
 
-- **Avalanche Bridge** - is capable of transferring a fixed list of tokens between Ethereum and Avalanche C-Chain. See the `@avalabs/bridge-avalanche` package.
-- **CCTP** - preferred for brdiging USDC between Ethereum and Avalanche C-Chain. See the `@avalabs/bridge-cctp` package.
+- **CCTP** - preferred for brdiging USDC between Ethereum and Avalanche C-Chain. See the `bridges/cctp` folder.
 
 Future bridges we plan to support:
 
+- **Avalanche Bridge** - is capable of transferring a fixed list of tokens between Ethereum and Avalanche C-Chain.
 - **Teleporter** - for moving tokens between subnets.
@@ -38,4 +38,123 @@ - **Cross-Chain Transfer** - for moving tokens between the three Avalanche Primary Network chains (X-Chain, C-Chain, and P-Chain).
 
-## How it works
+## Initialization
 
-TODO: Explain details of this api.
+```js
+import { createUnifiedBridgeService, Environment, BridgeTransfer } from '@avalabs/bridge-unified';
+
+// create a new service for an environment
+const unifiedService = createUnifiedBridgeService({
+  environment: Environment.TEST,
+});
+
+// init the service, fetch and setup its configs
+await unifiedService.init();
+
+// get the list of supported assets, grouped by chain IDs
+const assets = await unifiedService.getAssets()
+
+// get the bridge fee(s) of the provided transfer
+const fees = await unifiedService.getFees({...})
+
+// start a new bridge transfer and store its state
+const bridgeTransfer = await unifiedService.transferAsset({...})
+
+// create an update listener for tracking
+const updateListener = (transfer: BridgeTransfer) => {
+  console.log(transfer)
+}
+
+// start tracking the transfer's state. whenever the state changes, it will call the provided `updateListener`
+const { cancel, result } = await unifiedService.trackTransfer({bridgeTransfer, updateListener, ...})
+
+// immediatelly stops tracking and rejects the tracker's promise
+// cancel()
+
+// wait for the transfer to finish and get its final state
+const finalizedBridgeTransfer = await result
+```
+
+## API
+
+### createUnifiedBridgeService({ environment, disabledBridgeTypes? })
+
+Returns a new `unifiedBridgeService` for the given `environment`, using all supported bridge integrations by default. Individual bridges can be turned off via the `disabledBridgeTypes` array.
+
+#### environment
+
+Type: `Environment`
+
+Defines if the bridge service should use `testnet` or `mainnet`.
+
+#### disabledBridgeTypes
+
+Type: `BridgeType[] | undefined`
+
+Disables the integration of the provided `BridgeType`s.
+
+### unifiedBridgeService
+
+Contains all the required properties and methods to prepare, initiate or track a bridge transfer.
+Automatically picks the right (enabled) bridge integration to use based on the provided params.
+
+```js
+{
+  environment, // the provided Environment during initialization
+  bridges, // the list of enabled bridge integrations
+  init,
+  updateConfigs,
+  getAssets,
+  getFees,
+  transferAsset,
+  trackTransfer,
+}
+```
+
+#### init
+
+Type: `() => Promise<void>`
+
+Initializes the unified service by attempting to fetch the configurations of the enabled bridges.
+
+#### updateConfigs
+
+Type: `() => Promise<void>`
+
+Attempts to fetch the configurations of the enabled bridges.
+
+#### getAssets
+
+Type: `() => Promise<ChainAssetMap>`
+
+Returns the aggregated list of assets supported by the enabled bridges grouped by chain IDs.
+
+#### getFees
+
+Type: `(params: FeeParams) => Promise<AssetFeeMap>`
+
+Calculates and returns the bridge fees in `tokenAddress` - `amount` pairs for a given bridge transfer.
+
+#### transferAsset
+
+Type: `(params: TransferParams) => Promise<BridgeTransfer>`
+
+Starts a new bridge transfer, executing every required step in a single call.
+Transactions signing is done by either the provided `sourceProvider` or a custom `sign` callback.
+Returns a `BridgeTransfer` containing all the (known) initial values such as: environment, addresses, amount, fee, transaction hash, required and actual block confirmation counts, etc.
+
+#### trackTransfer
+
+Type: `(params: TrackingParams) => ({cancel, result})`
+
+Tracks the given `BridgeTransfer`'s progress and invokes the provided listener callback whenever a change happens.
+
+###### cancel
+
+Type: `() => void`
+
+If it's still pending, rejects the tracker's promise (`result`) immediatelly and breaks its loop under the hood.
+
+###### result
+
+Type: `Promise<BridgeTransfer>`
+
+Resolves with the finalized BridgeTransfer (if not canceled before).

src/types/bridge.ts

@@ -47,5 +47,5 @@ import type { Address } from 'viem';
   transferAsset: (params: TransferParams) => Promise<BridgeTransfer>;
-  trackTransfer: (transfer: TrackingParams) => { cancel?: () => void; result: Promise<BridgeTransfer> };
+  trackTransfer: (transfer: TrackingParams) => { cancel: () => void; result: Promise<BridgeTransfer> };
 };
 
 export type BridgeServiceFactory = (environment: Environment) => BridgeService;

No alert changes

Improved metrics

Total package byte prevSize

347731

increased by1%

Number of lines in readme file

159

increased by297.5%

No dependency changes