jevonearth commented 4 years ago

Introduction

Taquito currently has a signer API that supports the signing of raw bytes. For a richer interaction with wallets (such as TezBridge), by using raw bytes the wallet would have to “un-forge” the operation in order to display amount, destination, parameters and so forth. This may be undesirable or unnecessary for many use-cases.

Different wallets offer different APIs for “pre-forged” operations or “compound” operations. TezBridge’s has an API named “inject_operation”, which is a composition of forging, signing, broadcasting and estimation.

Goal

We are proposing a new "wallet API" in Taquito that aims to provide a common abstraction for dApp/App developers building with Taquito, that want to prompt a user for actions from the users wallet.

The Wallet API is for user-facing applications. In contrast, the existing Taquito "contract" API's intended scope can be defined as being suitable for backend functionality that does not require interaction with a user's wallet.

The Wallet API is defined as an interface, and can have different concrete implementations of providers.

For the prototype of this Wallet API we have made two implementations that satisfy the Wallet API interface:

BeaconWallet provider which supports the tzip-10 wallet interaction specification
TezBridge

Assumptions for BeaconWallet provider

For the tzip-10 wallet provider, the Wallet API assumes that the wallet in use (on the other end of the dApp <--> Wallet relationship) provides functionalities outlined in the tzip-10 spec.

The wallet API assumes that the wallet is responsible for the following actions:

prepare (set branch and counter. set fees, gas limit and storage limit. Include a reveal operation)
forge
sign
inject (can be implemented in both the Taquito side or the wallet side)

Returned data from BeaconWallet provider:

The wallet will return an operation hash via the BeaconWallet provider.
In case of an error, the wallet must return them to the caller.

Example usage from a Taquito user perspective

Setting up using Beacon SDK

const beaconWallet = new BeaconWallet()
await beaconWallet.init() // Request permissions
Tezos.setProvider({wallet: beaconWallet})
Tezos.wallet.transfer({to: "tz1.....", amount: 0.001})

Setting up using TezBridge

Tezos.setProvider({wallet: new TezBridgeWallet()})
Tezos.wallet.transfer({to: "tz1.....", amount: 0.001})

Discover PKH

const pkh = await Tezos.wallet.pkh()

Originate

const op = Tezos.wallet.originate({params});
await op.confirmation()

console.log(op.fees)

Transaction / Smart contract call

Tezos.wallet.transfer({params})

const op = contract.methods.myEntrypoint(myEntypointParameter).send()
await op.confirmation()

console.log(op.fees)

Delegation

const op = Tezos.wallet.delegation({params})
await op.confirmation()

console.log(op.fees)

Each of these method calls would do an operation request using the interaction standard API

Notes

We also aim to expose our current implementation through the wallet API. The current implementation only delegates the signing to a signer (wallet). In this context Taquito would take care of:

preparing
forging
~~signing~~
injecting

const wallet = new LegacyWalletProvider()

Tezos.setProvider({wallet})

Beacon SDK implementation details

In the context of beacon-sdk and tzip-10, most of Taquito calls will rely on the the operationRequest message

sequenceDiagram
    participant dApp
    participant Taquito
    participant BeaconSDK
    participant Wallet

    dApp ->> BeaconSDK: Setup BeaconSDK
    activate BeaconSDK
    Note over dApp,BeaconSDK: Step above includes requesting permission
    dApp ->> Taquito: Setup Taquito
    activate Taquito

    dApp ->> Taquito: Tezos.wallet.transfer(params)
    Taquito ->> BeaconSDK: operationRequest
    BeaconSDK ->> Wallet: operationRequest
    Wallet ->> Wallet: Prompt user
    Wallet ->> Wallet: Prepare, Forge, Sign, Inject
    Wallet ->> BeaconSDK: operation hash
    BeaconSDK ->> Taquito: operation hash
    Taquito ->> dApp: Operation Object
    deactivate Taquito
    deactivate BeaconSDK

TezBridge implementation details

In the context of TezBridge most of Taquito calls will rely on the inject_operations request

Taquito specific concern

How to keep wallet network and Taquito network in-sync?
Do we have a fixed time limit between the time a user calls Tezos.wallet.transfer and the promise is resolved.
How to handle page refresh between Tezos.wallet.transfer and the resolved promise?
Should we support batch operation through the Wallet API. ie including multiple transfer/originate and delegation in one call
- Tezos.wallet.batch(params).send()

Right now operation object returned by Taquito assume that a dry run has been done locally and expect the result of this dry run in their constructor

See: https://github.com/ecadlabs/taquito/blob/master/packages/taquito/src/operations/operations.ts#L100

This is a current limitation of the operation object and will need to be reworked (or we provide a different implementation) in order to create an operation object only from the operation hash.

[x] Add section to website
[x] Update existing documentation so we differentiate between the Contract API and the Wallet API.
[-] ~~Update the docusarus runnable code widget with the ability to use the Wallet API so that the user can choose what Wallet provider to use~~ @claudebarde made separate sections for each provider which is more helpful than having a switcher.