Installation

npm install @upcoming/multichain-widget

Usage

Import the component and accompanying styles:

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:

<MultichainWidget />

Props and Query params

It is possible to specify query params or pass some props to <MultichainWidget /> 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

The steps depend on the mode and on whether the source chain is Gnosis.

funding mode, non-Gnosis source chain

1. Cross-swap the token to xBZZ using Relay, with a gas top-up, both going straight to the user's wallet.

batch mode, non-Gnosis source chain

1. Cross-swap the token to xBZZ using Relay, with a gas top-up, both going to a temporary wallet.
2. Approve the xBZZ spending and create the postage batch, owned by the user's wallet.
3. Transfer any remaining xDAI to the user's wallet.

Gnosis source chain

1. Deposit xDAI to a temporary wallet.
2. Swap xDAI to xBZZ using SushiSwap, going to the user's wallet in funding mode and to the temporary wallet in batch mode.
3. In batch mode, approve the xBZZ spending and create the postage batch, owned by the user's wallet.
4. Transfer any remaining xDAI to the user's wallet.

Dependencies

Relay

We use the Relay API to cross-swap to xBZZ, together with a gas top-up in 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

Messages are posted to the window that hosts the widget: window.parent when the widget is embedded in an iframe, or window.opener when it is opened as a popup with window.open (there window.parent is the popup itself). Hosts should verify event.source and event.origin before trusting a message.

• { event: 'error', error }
• { event: 'finish' }
• { event: 'batch', batchId: 0x${string}, depth: number, amount: numberString, blockNumber: 0x${string} }
• { event: 'payment', phase: 'sent' | 'delivered', chainId: number, resumed: boolean, txHash?: 0x${string}, temporaryAddress?: 0x${string} }

Example:

{
    "event": "batch",
    "batchId": "0xfe48d3cd7ec9cdf455811894d63683b1fac8b358501b843892b372e355155b62",
    "depth": 21,
    "amount": "10453363201",
    "blockNumber": "0x2a828b8"
}

Payment events

The payment event tells the host that money is in flight, so it can avoid closing the widget after the point of no return, and can find the funds later if the flow is interrupted.

• phase: 'sent' — the payment transaction succeeded (txHash is on chainId, the source chain). Point of no return: the funds will be delivered to temporaryAddress whether or not the widget is still open.
• phase: 'delivered' — the funds arrived on temporaryAddress (xDAI from a Gnosis source chain, xBZZ plus a gas top-up from any other one); the remaining steps run on Gnosis (chainId is 100, no txHash).
• resumed: true — the temporary wallet was already funded, so the payment step was skipped and no new payment was made. Emitted with phase: 'delivered'; the funds are just as much in flight as after a fresh payment.
• temporaryAddress is present whenever the payment routes through the temporary wallet, which is where funds can get stranded if the widget is interrupted. It is absent when Relay delivers to the destination address directly (funding mode from a non-Gnosis chain): that path has no temporary wallet and no further steps, so it emits sent only — its completion is the finish event.

Example:

{
    "event": "payment",
    "phase": "delivered",
    "chainId": 100,
    "temporaryAddress": "0x45a1502382541Cd610CC9068e88727426b696293",
    "resumed": false
}

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.

Maintainers

• Cafe137