MIME-Version: 1.0
References: <CAPvWj7H9hg8EMCvDzWiq=f59KojHEGCm_iAP+FBaB+25=CLt0A@mail.gmail.com>
In-Reply-To: <CAPvWj7H9hg8EMCvDzWiq=f59KojHEGCm_iAP+FBaB+25=CLt0A@mail.gmail.com>
From: Erik Aronesty <erik@q32.com>
Date: Wed, 23 Dec 2020 16:13:29 -0500
Message-ID: <CAJowKg+wE2SO5hcSbcNzPCtjetgBxXo5ejkFUV=mQrxxUh1-5w@mail.gmail.com>
To: monokh <mnokhb@gmail.com>, 
 Bitcoin Protocol Discussion <bitcoin-dev@lists.linuxfoundation.org>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Subject: Re: [bitcoin-dev] BIP Proposal: Wallet Interface
Precedence: list

Obviously Bitcoin has a wallet api, intermingled with other protocol APIs:

https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_calls_list

For security, a standard wallet API should write a token/port to a
local file where the user can grab that token and use it (that's
basically how the existing bitcoind does it, with a username/password
living in a file... not as nice as a token/port, IMO)

Probably any such standards document should do its best to be
compatible with the existing APIs that so many are already familiar
with.   Or maybe I misunderstand the proposal.

- Erik

On Tue, Dec 22, 2020 at 9:48 AM monokh via bitcoin-dev
<bitcoin-dev@lists.linuxfoundation.org> wrote:
>
> Hi
>
> This is a first draft of a BIP we intend to submit. The main intention is=
 to define a simple interface that wallets and applications can agree on th=
at would cover the vast majority of use cases. This can enable writing bitc=
oin applications (e.g. time lock, multi sig) on the web that can be seamles=
sly used with any compatible wallets. We have implementations of such examp=
les but I don't want to turn this thread into a promotion and rather focus =
on the spec.
>
> Appreciate input from the list. Please share if there are existing effort=
s, relevant specs or use cases.
>
> ------------------------------
>
> A wallet interface specification for bitcoin applications
>
> ## Abstract
>
> This BIP describes an API for Bitcoin wallets and applications as a stand=
ard.
>
> ## Summary
>
> Bitcoin wallets should expose their address derivation and signing functi=
ons to external applications. The interface would be expressed as follows i=
n javascript:
>
> ```
> {
> // Wallet Metadata
> wallet: {
> name: 'Bitcoin Core'
> },
>
> // Request access to the wallet for the current host
> async enable: (),
>
> // Request addresses and signatures from wallet
> async request ({ method, params })
> }
> ```
>
> In the web context the interface could be exposed at the top level of a w=
ebpage, for example under `window.bitcoin`. However this spec does not inte=
nd to define any standards for how and where the interfaces should be expos=
ed.
>
> ## Motivation
>
> Due to the seldom available APIs exposed by wallets, applications (web or=
 otherwise) are limited in how they are able to interact. Generally only si=
mple sends have been available. A more robust API that introduces other req=
uests will promote richer Bitcoin applications.
>
> Additionally, wallet APIs have frequently included inconsistencies in the=
ir interfaces and behaviour. This has required applications to build and ma=
intain a separate client for each wallet, increasing the risk of bugs and u=
nintended behaviour as well as being a limiting factor for the adoption of =
usable bitcoin applications.
>
> With a standardised wallet API:
>
> - Wallets have a clear API to implement
> - Applications have a clear expectation of wallet interface and behaviour
> - Applications become agnostic to the wallet specifics, increasing choice=
 for users
>
> If more wallets implement the specification, applications will be develop=
ed more confidently by benefiting from the wallet interoperability. This cr=
eates a positive feedback loop.
>
> ## Specification
>
> For simplicity, the interface is defined in the context of web applicatio=
ns running in the browser (JS) however, they are simple enough to be easily=
 implemented in other contexts.
>
> ### General Rules
>
> - For sensitive functions (e.g. signing), wallet software should always p=
rompt the user for confirmation
>
> ### Types
>
> **UserDeniedError**
> An error type indicating that the application's request has been denied b=
y the user
> Type: Error
>
> **Hex**
> Type: String
> Example: `"0000000000000000000a24677957d1e50d70e67c513d220dbe8868c4c3aefc=
08"`
>
> **Address**
> Address details
> Type: Object
> Example:
>
> ```
> {
> "address": "bc1qn0fqlzamcfuahq6xuujrq08ex7e26agt20gexs",
> "publicKey": "02ad58c0dced71a236f4073c3b6f0ee27dde6fe96978e9a9c9500172e3f=
1886e5a",
> "derivationPath": "84'/1'/0'/0/0"
> }
> ```
>
> ### API
>
> The wallet must implement the following methods.
>
> **enable**
>
> The enable call prompts the user for access to the wallet.
>
> If successful, it resolves to an address (`**Address**` type) of the wall=
et. Typically the first external address to be used as an identity.
>
> **`UserDeniedError`** will be thrown if the request is rejected.
>
> **request**
>
> The request method must take one parameter in the following format:
>
> ```
> {
> "method": "wallet_methodName",
> "params": ["foo", "bar", "baz"]
> }
> ```
>
> For a list of mandatory methods see Table
>
> The wallet should reject request calls unless `enable` has been resolved.
>
> Sensitive requests that involve signing should always prompt the user for=
 confirmation
>
> On success the request should resolve to the response as defined in the m=
ethod table.
>
> **`UserDeniedError`** will be thrown if the request is rejected.
>
> **Mandatory methods**
>
> method: `wallet_getAddresses` params: [`index =3D 0, numAddresses =3D 1, =
change =3D false`]
> return: `[ Address ]`
> error: UserDeniedError
>
> method: `wallet_signMessage` params: `[ message, address ]`
> return: Signature `Hex`
> error: UserDeniedError
>
> method: `wallet_signPSBT` params: `[ [psbtBase64, inputIndex, address] ]`
> return: `psbtBase64`
> error: UserDeniedError
>
> method: `wallet_getConnectedNetwork` params: `[]`
> return: Network object `mainnet` | `testnet` | `regetst`
> error: UserDeniedError
>
> ## Rationale
>
> The purpose of the API is to expose a set of commonly used wallet operati=
ons. In addition, it should be flexible enough to serve for other requests =
such as node RPC calls.
>
> **Why is there a singular request call instead of named methods?**
> The transport layer for the requests cannot be assumed, therefore it is m=
uch more flexible to instead define an abstract format.
>
> **Why are the mandatory methods so primitive? Where is getBalance, getUtx=
os, ... ?**
> A wallet need not worry about providing every possible scenario for usage=
. The primitives of keys and signing can expose enough to applications to d=
o the rest. Applications should have flexibility in how they implement thes=
e functions. It is the role of a library rather than the wallet.
>
> ## Security Implications
>
> Great care should be taken when exposing wallet functionality externally =
as the security and privacy of the user is at risk.
>
> ### Signing
>
> Operations that trigger signing using private keys should be guarded behi=
nd confirmation screens where the user is fully aware of the nature of the =
transaction. In the example of a PSBT signature request, the outputs, the i=
nputs and which key is being used should be clearly marked.
>
> ### Privacy
>
> Some api methods expose metadata about the user, such as public keys. Dep=
ending on how privacy focused the wallet intends to be, the wallet could pr=
otect these behind a confirmation. Commonly the wallet just needs to give t=
he origin access to all of its public keys, however it could also allow the=
 option to expose only selected derivation paths.
>
> -monokh
>
> _______________________________________________
> bitcoin-dev mailing list
> bitcoin-dev@lists.linuxfoundation.org
> https://lists.linuxfoundation.org/mailman/listinfo/bitcoin-dev