Blossom JS Library

A JavaScript library that provides an interface to the Blossom browser extension.

Installation

The library can be installed via npm:

npm install --save @fairdatasociety/blossom

Usage

Blossom class

All interaction with the Blossom browser extension is established through the Blossom class:

import { Blossom } from '@fairdatasociety/blossom'

By default the class will connect to the Blossom browser extension using its ID from the Google store. If you are running your version of the extension the class can be configured with a different extension ID.

const blossom = new Blossom() // Using the default Blossom ID from the Google store

const blossom = new Blossom('Blossom Extension ID...') // Using custom Blossom ID

Each dApp should be executed from a BZZ link (e.g. http://dApp-or-ENS-name.swarm.localhost:1633 or http://localhost:1633/bzz/dApp-or-ENS-name/). In that case dApp's ID is available as blossom.dappId property.

To test if connection with the Blossom extension is established, call the echo method:

const text = await blossom.echo<string>('test')
console.log(text) // 'test'

FDP Storage

Pod access

If the user is logged in, dApp can access its own pod. Each dApp can have only one pod and its name must be the same as the blossom.dappId property.

To check if dApp's pod is already created:

const podIsCreated = await blossom.fdpStorage.personalStorage.isDappPodCreated()

If not created, then it can be created by calling:

const pod = await blossom.fdpStorage.personalStorage.create(blossom.dappId)

If other pod name is provided, that pod can be created/accessed only if the user allows it. Otherwise an Access denied error will be thrown.

For applications that need access to all pods (like file system apps, etc.), they can request full access:

const allowed = await blossom.fdpStorage.personalStorage.requestFullAccess()

File access

dApp can execute various operations with allowed pods, like creating, reading files and directories, etc.

For example, to create a directory:

const directory = await blossom.fdpStorage.directory.create(blossom.dappId, '/example')

Then, to upload a file there:

const file = await blossom.fdpStorage.file.uploadData(blossom.dappId, '/example/new-file.txt', 'File content')

And to download the same file:

const content = await blossom.fdpStorage.file.downloadData(blossom.dappId, '/example/new-file.txt')
console.log(content.text()) // 'File content'

NOTE: For more available methods, check the fdp-storage repo

Signer

dApps can sign any data using their default pod's private key.

const signature = await blossom.signer.signMessage(blossom.dappId, 'Data...')

Wallet

Library provides methods for interaction with Blossom wallet.

To get information about the user:

const info = await blossom.wallet.getAccountInfo()
console.log(info.address) // user's address

NOTE: The user must allow access to this information, othrwise an "Access denied" error is thrown

To get balance of currently logged in user:

const balanceString = await blossom.wallet.getUserBalance()
console.log(BigNumber.from(balanceString)) // result can be converted to BigNumber object

dApp can send funds as well, but the user must allow it:

await blossom.wallet.sendTransaction('0x1234...', '1000000000')

Terminating connection

Once when the instance of the Blossom class is not needed anymore, connection with the extension can be terminated.

blossom.closeConnection()

Development

To watch for changes in the source code and recompile the library on change:

npm start

Build

To build the library:

npm run build

Tests

Tests use the puppeteer project to interact with the library and the Blossom extension. Because of that, tests need web pages that are going to be interacted with. Such test web pages are located inside the test/webpages directory. Each page contains elements that can be interacted with to trigger various events, and placeholder elements that are used to show results of various operations.

Before running tests, the complete environment must be started. To start the environment and the extension check the extension's readme.

To run a web server that will serve the test web pages, execute:

npm run serve

The Blossom extension and the Swarm extension must be compiled. For that, check the readme file of the root project.

Now when the environment is ready, tests are executed by running:

npm test