Skip to content

Commit 029ffc5

Browse files
lnbc1QWFyb24lnbc1QWFyb24
committed
Update docs
1 parent a0dfea9 commit 029ffc5

File tree

1 file changed

+188
-21
lines changed

1 file changed

+188
-21
lines changed

‎README.md

Lines changed: 188 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Onboard
22

3-
JavaScript library to easily onboard users to ethereum apps by enabling wallet selection, connection and readiness and real time state updates.
3+
JavaScript library to easily onboard users to ethereum apps by enabling wallet selection, connection, readiness and real time state updates.
44

55
## Install
66

@@ -9,29 +9,34 @@ JavaScript library to easily onboard users to ethereum apps by enabling wallet s
99
## Quick Start with Default Modules
1010

1111
```javascript
12-
import Onboard from 'bn-onboard'
12+
import { init, modules } from "bn-onboard"
1313

1414
// initialize onboard
15-
const onboard = Onboard.init({
16-
dappId: 'Your apiKey here',
15+
const onboard = init({
16+
dappId: "Your apiKey here",
1717
networkId: 1,
1818
subscriptions: {
19-
address: address => console.log('user address has changed:', address)
20-
network: network => console.log('user network has changed:', network)
21-
balance: balance => console.log('user balance has changed:', balance)
22-
wallet: wallet => console.log('a new wallet has been selected by user', wallet.provider, wallet.name)
19+
address: address => console.log("user address has changed:", address),
20+
network: network => console.log("user network has changed:", network),
21+
balance: balance => console.log("user balance has changed:", balance),
22+
wallet: wallet =>
23+
console.log(
24+
"a new wallet has been selected by user",
25+
wallet.provider,
26+
wallet.name
27+
)
2328
},
2429
modules: {
2530
// default wallets that are included: MetaMask, Dapper, Coinbase, Trust, WalletConnect
26-
walletSelect: Onboard.modules.select({
31+
walletSelect: modules.select.defaults({
2732
// if you want fortmatic as a wallet option
2833
fortmaticInit: { apiKey: "Your fortmatic key here" },
2934
// if you want portis as a wallet option
3035
portisInit: { apiKey: "Your portis key here" },
3136
networkId: 4
3237
}),
3338
// default ready steps are: connect, network, balance
34-
walletReady: Onboard.modules.ready({
39+
walletReady: modules.ready.defaults({
3540
networkId: 4,
3641
minimumBalance: "200000000000000000"
3742
})
@@ -59,10 +64,10 @@ const options = {
5964
},
6065
modules: {
6166
walletSelect: {
62-
heading: "Select a Wallet"
63-
description: "Please select a wallet that you would like to use with this Dapp"
67+
heading: "Select a Wallet",
68+
description: "Please select a wallet that you would like to use with this Dapp",
6469
wallets: {
65-
mobile: [mobileWalletModuleOne, mobileWalletModuleTwo, ...]
70+
mobile: [mobileWalletModuleOne, mobileWalletModuleTwo, ...],
6671
desktop: [desktopWalletModuleOne, desktopWalletModuleTwo, desktopWalletModuleThree, ...]
6772
}
6873
},
@@ -77,8 +82,8 @@ const onboard = Onboard.init(options)
7782

7883
```javascript
7984
const options = {
80-
dappId: String,
81-
networkId: Number,
85+
dappId: String, // see below
86+
networkId: Number, // see below
8287
subscriptions: {
8388
address: Function, // Called with the current account address of the user [String]
8489
network: Function, // Called with the current network id the users' wallet is connected to [Number]
@@ -87,14 +92,14 @@ const options = {
8792
},
8893
modules: {
8994
walletSelect: {
90-
heading: String,
91-
description: String,
95+
heading: String, // The heading for the wallet select modal
96+
description: String, // The description for the wallet select modal
9297
wallets: {
93-
mobile: Array,
94-
desktop: Array
98+
mobile: Array, // array of mobile wallet modules
99+
desktop: Array // array of desktop wallet modules
95100
}
96101
},
97-
walletReady: Array
102+
walletReady: Array // array of wallet readiness modules
98103
}
99104
}
100105
```
@@ -136,7 +141,7 @@ Once a wallet is selected, you will want to make sure that the user's wallet is
136141
const readyToTransact = await onboard.walletReady()
137142
// returns a Promise that:
138143
// resolves with true if user is ready to transact
139-
// resolves with false if user exited before completing all prepare wallet modules
144+
// resolves with false if user exited before completing all wallet readiness modules
140145
```
141146

142147
This function will run through the onboarding modules sequentially, making sure the user has passed the condition contained in each module and eventually resolves with `true` if the user completed the sequence. This means that the user is ready to transact. This function is useful to call before every transaction to make sure that nothing has changed since the last time it was called.
@@ -156,3 +161,165 @@ Available parameters that you can edit are:
156161
darkMode: Boolean, // (default: false)
157162
}
158163
```
164+
165+
## Modules
166+
167+
### Wallet Select Modules
168+
169+
The wallet select modules are functions that return a wallet object. The following modules are currently available:
170+
171+
- `defaults`: A meta module that quickly initializes all of the default modules into the correct format (requires initialization object)
172+
173+
#### Desktop Wallets
174+
175+
- `metamask`
176+
- `dapper`
177+
- `walletConnect`
178+
- `portis` (requires initialization)
179+
- `fortmatic` (requires initialization)
180+
181+
#### Mobile Wallets
182+
183+
- `trust`
184+
- `coinbase`
185+
- `walletConnect`
186+
- `portis` (requires initialization)
187+
- `fortmatic` (requires initialization)
188+
189+
`defaults` Initialization:
190+
191+
```javascript
192+
modules.select.defaults({
193+
heading: String, // Override the default heading [optional]
194+
description: String, // Override the default description [optional]
195+
networkId: Number, // Required if you want the Portis or Fortmatic modules to be included
196+
portisInit: Object, // initialization object for Portis module (see below)
197+
fortmaticInit: Object // initialization object for Fortmatic module (see below)
198+
})
199+
```
200+
201+
`portis` Initialization:
202+
203+
```javascript
204+
portis({
205+
apiKey: String, // your Portis api key
206+
network: String // the name of network you want to connect to
207+
})
208+
```
209+
210+
`fortmatic` Initialization:
211+
212+
```javascript
213+
fortmatic({
214+
apiKey: String, // your Portis api key
215+
network: String // the name of the network you want to connect to
216+
})
217+
```
218+
219+
#### Example
220+
221+
```javascript
222+
import { init, modules } from "bnc-onboard"
223+
224+
// PICK AND CHOOSE MODULES
225+
226+
const { portis, dapper, metamask, fortmatic } = modules.select
227+
228+
const onboard = init({
229+
// ...
230+
modules: {
231+
walletSelect: {
232+
heading: "Select a Wallet",
233+
description:
234+
"Please select the wallet that you would like to use with this Dapp",
235+
wallets: {
236+
desktop: [
237+
portis({ apiKey: 'sdda-w2-ds3', network: 'main' })
238+
dapper(),
239+
metmask(),
240+
],
241+
mobile: [fortmatic({apiKey: 'sd-3d3-d', network: 'main'})]
242+
}
243+
}
244+
//....
245+
}
246+
})
247+
248+
// OR
249+
250+
// USE ALL OF THE DEFAULT MODULES
251+
252+
const onboard = init({
253+
// ...
254+
modules: {
255+
walletSelect: modules.select.defaults({
256+
portisInit: { apiKey: "Your portis key here" },
257+
networkId: 4
258+
}),
259+
// ...
260+
}
261+
})
262+
```
263+
264+
### Wallet Ready Modules
265+
266+
The wallet ready modules are functions that return a function that will be called with the current user state. The module will return a modal object if that state is invalid or `undefined` if the state is valid. The following default modules are available:
267+
268+
- `defaults`: A meta module that quickly initializes all of the default modules into the correct format (requires initialization object)
269+
- `connect`: Checks that the dapp has access to accounts and fires the connect function if the selected wallet has one
270+
- `network`: Checks that the users' wallet is connected to the desired network (requires initialization argument)
271+
- `balance`: Checks that the users' account has enough balance as defined when initialized (requires initialization argument)
272+
273+
`defaults` Initialization:
274+
275+
```javascript
276+
modules.ready.defaults({
277+
networkId: Number, // The network id your dapp runs on
278+
minimumBalance: String // the minimum balance in wei required to interact with your dapp
279+
})
280+
```
281+
282+
`network` Initialization:
283+
284+
```javascript
285+
network(Number) // the network id your dapp runs on
286+
```
287+
288+
`balance` Initialization:
289+
290+
```javascript
291+
balance(String) // the minimum balance in wei required to interact with your dapp
292+
```
293+
294+
#### Example
295+
296+
```javascript
297+
import { init, modules } from "bnc-onboard"
298+
299+
// PICK AND CHOOSE MODULES
300+
301+
const { connect, network, balance } = modules.ready
302+
303+
const onboard = init({
304+
// ...
305+
modules: {
306+
//....
307+
walletReady: [connect(), network(1), balance("400000000000")]
308+
}
309+
})
310+
311+
// OR
312+
313+
// USE ALL OF THE DEFAULT MODULES
314+
315+
const onboard = init({
316+
// ...
317+
modules: {
318+
// ...
319+
walletReady: modules.ready.defaults({
320+
networkId: 1,
321+
minimumBalance: "400000000000"
322+
})
323+
}
324+
})
325+
```

0 commit comments

Comments
 (0)