@proton/link

v4.2.18

Published

3 months ago

Library for authenticating and signing transactions using the Proton Link protocol

Downloads

533

0High
0Medium
0Low

jafri

Proton Link

Persistent, fast and secure signature provider for Proton blockchain built on top of Signing Requests (EEP-7)

Key features:

Persistent account sessions
End-to-end encryption (E2EE)
Account-based identity proofs
Cross-device signing
Network resource management
Open standard

Resources:

Examples:

Simple Examples

Installation

The proton-link package is distributed both as a module on npm and a standalone bundle on unpkg.

Browser using a bundler (recommended)

Install Proton Link and a transport:

yarn add @proton/link @proton/browser-transport
# or
npm install --save @proton/link @proton/link-browser-transport

Import them into your project:

import ProtonLink from '@proton/link'
import ProtonBrowserTransport from '@proton/browser-transport'

Browser using a pre-built bundle

Include the scripts in your <head> tag.

<script src="https://unpkg.com/@proton/[email protected]"></script>
<script src="https://unpkg.com/@proton/[email protected]"></script>

ProtonLink and ProtonBrowserTransport are now available in the global scope of your document.

Usage

First you need to instantiate your transport and the link.

const transport = new ProtonBrowserTransport()
const link = new ProtonLink({
    transport,
    chains: [
        {
            chainId: 'aca376f206b8fc25a6ed44dbdc66547c36c6c33e3a119ffbeaef943642f0e906',
            nodeUrl: 'https://eos.greymass.com',
        }
    ],
})

Now you have a link instance that can be used in the browser to login and/or transact. Refer to the proton-link-browser-transport README for a list of available options within the transport.

Create a user session

To create a persistent session where you can push multiple transaction to a users wallet you need to call the login method on your link instance and pass your application name.

// Perform the login, which returns the users identity
const identity = await link.login('mydapp')

// Save the session within your application for future use
const {session} = identity
console.log(`Logged in as ${session.auth}`)

Perform a transaction with a user session

Using the session you have persisted within your applications state from the user login, you can now send transactions through the session to the users wallet using the [transact] method.

const action = {
    account: 'eosio',
    name: 'voteproducer',
    authorization: [session.auth],
    data: {
        voter: session.auth.actor,
        proxy: 'greymassvote',
        producers: [],
    },
}

session.transact({action}).then(({transaction}) => {
    console.log(`Transaction broadcast! Id: ${transaction.id}`)
})

Restoring a session

If a user has previously logged in to your application, you can restore that previous session by calling the [restoreSession] method on your link instance.

link.restoreSession('mydapp').then(({session}) => {
    console.log(`Session for ${session.auth} restored`)
    const action = {
        account: 'eosio',
        name: 'voteproducer',
        authorization: [session.auth],
        data: {
            voter: session.auth.actor,
            proxy: 'greymassvote',
            producers: [],
        },
    }
    session.transact({action}).then(({transaction}) => {
        console.log(`Transaction broadcast! Id: ${transaction.id}`)
    })
})

Additional Methods

List all available sessions: listSessions
Removing a session: removeSession

One-shot transact

To sign action(s) or a transaction using the link without logging in you can call the transact method on your link instance.

const action = {
    account: 'eosio',
    name: 'voteproducer',
    authorization: [
        {
            actor: '............1', // ............1 will be resolved to the signing accounts name
            permission: '............2', // ............2 will be resolved to the signing accounts authority (e.g. 'active')
        },
    ],
    data: {
        voter: '............1', // same as above, resolved to the signers account name
        proxy: 'greymassvote',
        producers: [],
    },
}
link.transact({action}).then(({signer, transaction}) => {
    console.log(
        `Success! Transaction signed by ${signer} and bradcast with transaction id: ${transaction.id}`
    )
})

You can find more examples in the examples directory at the root of this repository.

Transports

Transports in Proton Link are responsible for getting signature requests to the users wallet when establishing a session or when using Proton Link without logging in.

Available transports:

Package | Description ---------| --------------- proton-browser-transport | Browser overlay that generates QR codes or triggers local URI handler if available

Protocol

The Proton Link protocol uses EEP-7 identity requests to establish a channel to compatible wallets using an untrusted HTTP POST to WebSocket forwarder (see buoy node.js).

A session key and unique channel URL is generated by the client which is attached to the identity request and sent to the wallet (see transports). The wallet signs the identity proof and sends it back along with its own channel URL and session key. Subsequent signature requests can now be encrypted to a shared secret derived from the two keys and pushed directly to the wallet channel.

📘 Protocol specification

Developing

You need Make, node.js and yarn installed.

Clone the repository and run make to checkout all dependencies and build the project. See the Makefile for other useful targets. Before submitting a pull request make sure to run make lint.