Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ethersphere/multichain-widget


https://github.com/ethersphere/multichain-widget

Last synced: 3 months ago
JSON representation

Awesome Lists containing this project

README 

          
# Installation



```

npm install @upcoming/multichain-widget

```



# Usage



Import the component and accompanying styles:



```ts

import '@rainbow-me/rainbowkit/styles.css'

import { MultichainWidget } from '@upcoming/multichain-widget'

import '@upcoming/multichain-widget/styles.css'

```



Then simply place the component in your app:



```tsx



```



## Props and Query params



It is possible to specify query params or pass some props to `` to customize its behavior:



### `theme`



Colors, fonts, sizes, etc. can be overwritten by using this prop.



Does not support query params.



### `hooks`



Callbacks can be specified for various events in the flow. The most important hook is the `onCompletion` hook, which is called when the flow is completed successfully.



Applications embedding the widget and conditionally rendering it can use this hook to unmount the widget when the flow is done.



Does not support query params.



### `settings`



Mainly used to customize the `gnosisJsonRpcProviders` array.



Does not support query params.



### `intent`



The intent modifies the information text displayed on the first screen. Possible values are `initial-funding`, `postage-batch` and `arbitrary`.



Can be specified in the query params with the `intent` key.



### `destination`



The default target address where the xBZZ and xDAI tokens will be sent.



Can be specified in the query params with the `destination` key.



### `dai`



The default amount of xDAI to receive at the end of the flow.



Can be specified in the query params with the `dai` key.



### `bzz`



The default amount of xBZZ to receive at the end of the flow.



Can be specified in the query params with the `bzz` key.



# Flow



1. Cross-swap a token to xDAI using Relay, goes to a temporary wallet.

2. Swap xDAI to xBZZ using SushiSwap, goes to the user's wallet.

3. Transfer any remaining xDAI to the user's wallet.



# Dependencies



### Relay



We use the Relay API to cross-swap to xDAI.



### SushiSwap



We use SushiSwap contracts and its API to swap xDAI to xBZZ.



# Considerations



## Test Selectors



### Screen 1



#### Always Present



-   `data-test-id="intent"`

-   `data-test-id="target-address-input"`

-   `data-test-id="xdai-input"`

-   `data-test-id="xbzz-input"`

-   `data-test-id="continue"`

-   `data-test-id="export-keys"`



#### Conditional



-   `data-test-id="error-invalid-address"`

-   `data-test-id="error-bad-address-checksum"`

-   `data-test-id="error-not-enough-bzz"`



### Screen 2



#### Always Present



-   `data-test-id="go-back"`

-   `data-test-id="readonly-source-address"`

-   `data-test-id="readonly-target-address"`

-   `data-test-id="source-chain-input"`

-   `data-test-id="source-chain-input__1"` the number represents the network id, in this case 1 for Ethereum Mainnet

-   `data-test-id="source-token-input"`

-   `data-test-id="source-token-input__0xdac17f958d2ee523a2206206994597c13d831ec7"` the address represents the token, in this case USDT

-   `data-test-id="swap-summary"` (e.g. "You will swap 0.0814 (~$0.081) USDT from Ethereum to fund:")

-   `data-test-id="xdai-display__left"` (e.g. "0.01 xDAI")

-   `data-test-id="xdai-display__right"` (e.g. "$0.01")

-   `data-test-id="xbzz-display__left"` (e.g. "0.500 xBZZ")

-   `data-test-id="xbzz-display__right"` (e.g. "$0.06")

-   `data-test-id="quote-status"`

-   `data-test-id="quote-status__description"` (e.g. "Quote available")

-   `data-test-id="fund"`



#### Conditional



-   `data-test-id="quote-status__completed"`

-   `data-test-id="quote-status__pending"`

-   `data-test-id="quote-status__failed"`



### Screen 3



#### Always Present



-   `data-test-id="go-back"` disabled

-   `data-test-id="readonly-source-address"`

-   `data-test-id="readonly-target-address"`

-   `data-test-id="status-step-1"`

-   ...

-   `data-test-id="status-step-6"`

-   `data-test-id="fund"` disabled



#### Conditional



-   `data-test-id="status-step-1__pending"`

-   `data-test-id="status-step-1__skipped"`

-   `data-test-id="status-step-1__completed"`

-   `data-test-id="status-step-1__in-progress"`

-   `data-test-id="status-step-1__failed"`

-   ...

-   `data-test-id="status-step-6__pending"`

-   `data-test-id="status-step-6__skipped"`

-   `data-test-id="status-step-6__completed"`

-   `data-test-id="status-step-6__in-progress"`

-   `data-test-id="status-step-6__failed"`



## Theme



Most styles can be overwritten by passing a `theme` prop to the `MultichainWidget` component.



## Temporary wallet persistence



A backup of every generated private key is stored in `localStorage` with a timestamp suffix to avoid collisions.



## Reactivity



Hooks can be set by passing `hooks` prop to the `MultichainWidget` component. Currently supported hooks are:



-   `beforeTransactionStart`

-   `onFatalError`

-   `onCompletion`

-   `onUserAbort`



# Postage batch creation



1. Pass the `mode=batch` query param to the widget to switch to batch creation mode.

2. Pass `destination=0x${string}` to specify the desired owner of the postage batch. This is NOT related to the payer address.

3. Recommended to pass `intent=postage-batch` to adjust the information text on the first screen.

4. Optionally pass the `reserved-slots=2` query param to specify the number of intended reserved slots per bucket within the batch. This adjusts the capacity displayed on the first page and shifts the underlying depth values.



Example:



```

https://fund.ethswarm.org/?mode=batch&destination=0x45a1502382541Cd610CC9068e88727426b696293&intent=postage-batch&reserved-slots=2

```



## iframe messages



-   `{ event: 'error', error }`

-   `{ event: 'finish' }`

-   `{ event: 'batch', batchId: 0x${string}, depth: number, amount: numberString, blockNumber: 0x${string} }`



Example:



```json

{

    "event": "batch",

    "batchId": "0xfe48d3cd7ec9cdf455811894d63683b1fac8b358501b843892b372e355155b62",

    "depth": 21,

    "amount": "10453363201",

    "blockNumber": "0x2a828b8"

}

```



## Mocking



Adding the `mocked=true` query param to the widget URL will make the widget use mocked data and skip actual transactions. This is useful for testing and development purposes.