It uses the resources from the `@poanet/tokenbridge-bw-exchange` npm package to define new assets and exchange pairs.
### Introduction
The [Burner Wallet 2.0](https://github.com/burner-wallet/burner-wallet-2) is a modular, extendable and customizable web application.
It provides a set of packages and plugins that allow you to extend the basic functionality. Here we will focus on the Assets package and the Exchange Plugin.
#### Assets
You can add any native or ERC20 token to track its balance and send transactions. For example you can define a new ERC20 and add it to the wallet:
```javascript
import { xdai, dai, eth, ERC20Asset } from '@burner-wallet/assets';
const test = new ERC20Asset({
id: 'tst', // The internal ID used by the wallet.
name: 'Test Token', // The display name that will be displayed to the user.
network: '1', // The chain ID of the chain the token is deployed to.
address: '0x52ad726d80dbb4A9D4430d03657467B99843406b' // Address where the token contract is deployed
});
const core = new BurnerCore({
assets: [test, xdai, dai, eth],
});
```
The `ERC20Asset` class extends from the `Asset` class. The `Asset` class provides several methods to allow the wallet interact with the token.
The following are the most important to pay attention and that could be overridden if your token behaves differently.
-`getBalance`: Indicates how to get the balance of your asset.
-`startWatchingAddress`: Indicates how to listen to value transfers incoming into your account.
-`_send`: Indicates how to send value to another account.
#### Gateways
Gateways can be thought of as “wrapped RPC providers”, as they transmit data from the wallet to endpoints such as Infura.
Gateways use the `network` id from the assets to select the correct endpoints.
The `@burner-wallet/core` module contains some standard gateways:
- InfuraGateway
- XDaiGateway
- InjectedGateway (which transmits messages through an injected Web3 provider such as Metamask).
#### Exchange Plugin
The `@burner-wallet/exchange` package is an extendable plugin for implementing asset exchanges and bridges.
The exchange module accepts an array of trading pairs.
```
const exchange = new Exchange({
pairs: [new Pair1(), new Pair2()]
})
```
`Pair` is an abstract class that defines the interface for trading pairs. If you would like to add custom trading functionality, you can extend this class and implement it's methods:
-`estimateAtoB`: Indicates how to estimate the B Asset the user will receive for the amount of A Asset. For example Fees could be considered here. This method returns the amount to be received, and a custom message to display in UI.
-`estimateBtoA`: Indicates how to estimate the A Asset the user will receive for the amount of B Asset. For example Fees could be considered here. This method returns the amount to be received, and a custom message to display in UI.
-`exchangeAtoB`: Indicates how to send A Asset to be exchanged for B Asset. Here you can add logic to detect exchange finalization for example for a more complex exchange operation like bridges.
-`exchangeBtoA`: Indicates how to send B Asset to be exchanged for A Asset. Here you can add logic to detect exchange finalization for example for a more complex exchange operation like bridges.
Exchange pairs examples:
- [XDAIBridge](https://github.com/burner-wallet/burner-wallet-2/blob/develop/packages/exchange/src/pairs/XDaiBridge.ts): It allows the user to exchange the pair DAI <> xDAI. Since validators need to verify the transaction, and release the tokens on the other network, this pair detects the exchange finalization by listening to events on the bridge contracts.
- [Uniswap](https://github.com/burner-wallet/burner-wallet-2/blob/develop/packages/exchange/src/pairs/Uniswap.ts): It allows the user to exchange the pair DAI <> ETH by using Uniswap. In this case, `exchangeAtoB` is extended for converting DAI to ETH, since it requires performing two transactions. First calling `approve` on the token contract and then calling the method from the Uniswap contract.
#### TokenBridge Plugin
The [TokenBridge Burner Wallet 2 Plugin](https://github.com/poanetwork/tokenbridge/tree/develop/burner-wallet-plugin/tokenbridge-bw-exchange) provides some generic resources that can be used and extended:
-`ERC677Asset` - A representation of an Erc677 token
The asset `BridgeableERC20Asset` extends from `ERC20Asset` and overrides some methods:
-`_send`: If the asset detects that receiver is a bridge/mediator contract and it has on of the supported bridge modes, the tokens are sent using `approve()` + `relayTokens`, otherwise, regular ERC20 `transfer()` is used.
The asset `NativeMediatorAsset` extends from the `NativeAsset` of the burner wallet core. It extends the functionality with the following method:
-`scanMediatorEvents`: Add logic to watch transfer from mediator contracts to the wallet account to display it in the activity list.
-`getTx`: Overrides the logic to return the stored information about a transfer transaction to avoid errors on the information displayed.
The pair `Mediator` extend from some other classes that has `Pair` as base. It implements the previous mentioned methods to estimate and exchange the assets. It also implements some methods to detect the exchange finalization.
Here are some details of the implemented methods:
-`estimateAtoB`: Gets the fee, calculates the amount of B Asset the user will receive and sets a custom message to be displayed mentioning the fee charges.
-`estimateBtoA`: Gets the fee, calculates the amount of A Asset the user will receive and sets a custom message to be displayed mentioning the fee charges.
-`exchangeAtoB`: Sends A Asset to the mediator contract. Then it calls `detectExchangeAToBFinished`.
-`exchangeBtoA`: Sends B Asset to the mediator contract. Then it calls `detectExchangeBToAFinished`.
-`detectExchangeAToBFinished`: Wait for events emitted by the mediator contract to detect the exchange finalization.
-`detectExchangeBToAFinished`: Wait for events emitted by the mediator contract to detect the exchange finalization.
The pair `MediatorErcToNative` extend from `Mediator` as base. It overrides `estimateAtoB` and `estimateBtoA` to use a different manner of retrieving bridging fees that are specific for erc-to-native mediator.
The gateway `TokenBridgeGateway` extends from the `Gateway` class of the burner wallet core. It provides access from the wallet to the following networks:
-`my-plugin` - is the folder where the plugin code is located. To change the name of the plugin it is necessary to update the folder name `my-plugin` and all mentions to `my-plugin` to the new name of your plugin.
Inside `my-plugin` you can find the files that defines the resources to be exposed by the plugin to be used by the burner wallet in order to interact with the ERC677 to ERC677 bridge extension:
-`Stake` - extends from `ERC677Asset` defined in `@poanet/tokenbridge-bw-exchange`
-`xStake` - extends from `ERC677Asset` defined in `@poanet/tokenbridge-bw-exchange`
-`StakeBridge` - extends from `Mediator` defined in `@poanet/tokenbridge-bw-exchange`
In this repo example case, the class `StakeBridge` extends the `Mediator` class but has some differences on how to estimate the values and calculate the transfers fees.
That's why it overrides the methods:
-`estimateAtoB`: To add specific logic to get the fee from the A to B exchange and estimate the value that will be received.
-`estimateBtoA`: To avoid fee calculations since there are no fees for B to A exchange.
Inside the wallet folder, the file `wallet/src/index.tsx` integrates the plugin into the wallet by importing the resources in the following line:
```
import { Stake, xStake, StakeBridge } from 'my-plugin'
```
To be able to use and to display the balances for Stake and xStake it is necessary to list them in the list of assets as follow:
```
const core = new BurnerCore({
...
assets: [Stake, xStake]
})
```
Then, in order to perform exchange operations between the assets it is needed that the defined pair is included in the Exchange plugin as follows:
```
const exchange = new Exchange({
pairs: [new StakeBridge()]
})
```
### Clone the sample repo
Clone the sample repo to create a plugin project that uses the TokenBridge plugin. This sample repo contains a ready to publish plugin for a ERC677 to ERC677 bridge extension, but you can later modify it to define your own resources.
The project includes a burner wallet instance where you can test the implementation of the plugin in testnet. For that, you have to make sure that the build step was performed and that the plugin resources you modified are correctly imported and used in the `src/index.tsx` file of the `test-wallet` folder.
The project includes a burner wallet instance where you can use the implementation of the plugin. For that, you have to make sure that the build step was performed and that the plugin resources you modified are correctly imported and used in the `src/index.tsx` file of the `wallet` folder.