Return-Path: Received: from whitealder.osuosl.org (smtp1.osuosl.org [140.211.166.138]) by lists.linuxfoundation.org (Postfix) with ESMTP id DB7E7C0893 for ; Fri, 25 Dec 2020 18:11:30 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id CF8FB8677C for ; Fri, 25 Dec 2020 18:11:30 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from whitealder.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id xRg4fqeeqMgZ for ; Fri, 25 Dec 2020 18:11:26 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mail-pj1-f48.google.com (mail-pj1-f48.google.com [209.85.216.48]) by whitealder.osuosl.org (Postfix) with ESMTPS id 31C2086777 for ; Fri, 25 Dec 2020 18:11:26 +0000 (UTC) Received: by mail-pj1-f48.google.com with SMTP id m5so2747930pjv.5 for ; Fri, 25 Dec 2020 10:11:26 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=content-transfer-encoding:from:mime-version:subject:date:message-id :references:cc:in-reply-to:to; bh=g24Gedv1HN5u4O9FSRfnMEGZ9TarVvhfzR+VBGBWGD4=; b=j5pjxHvYx+kKcBzveO/PlbiE/p/aKmZZbNRIdoONR63v92kADG12mnbj6jKwGckC/F myZDsid/JZDD4RKrO7NgH52vhQJ3P+3UFNVbLmo5ueU4IF6bH2IfHJOQmOJsDXckOjtA 0DggZ2QNZe5q07X+SAmeWlypFut2UWoPCnRnFnBuHyLzLIroLvnNE9MbgVFdbZL3JdVs GV86S0Qsb8LIlD02gy2N8aiWgwA7cCbtTjt0U06rbSi2fQaz5JUs6ltjKFu9YQ09U7mM ellYWnB+4Q7GUhVNksXLXKMBw1z0H3lXs/aAYDteSQfzPhP6ddlXKfbepnA+8OhmOLYP y1mw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:content-transfer-encoding:from:mime-version :subject:date:message-id:references:cc:in-reply-to:to; bh=g24Gedv1HN5u4O9FSRfnMEGZ9TarVvhfzR+VBGBWGD4=; b=XI534nybnUchvgVuxD3dBSBoXmbCBvctUXnwPwOy/4su5Ckb1qCixWVoVIosoAH/Wa cSULBsCn/TrUwQM+fx/ijk7iycZmWU2e3C8Whz1rTTtlS5EvL5dN/Dnf2tTG6kWZD34c nCBB57EZnYCSAa0OkS49gDISLen37JsPpcqiNA9G3X3zVvTFd3+VVJtbtBpiJ1W9oh17 xF3NOK8lMCXqitgkuhsro+qI2w/oFzq40nvxw3ayVOO+lx7Ji9igVW2eNPuD+qqMpgZf YHapU3dXVufPsbH+sqnyvTX60HdIQqYjU5WK81Wgz0ovS6JCLFIIo38jadEEY/5PywZz hfSw== X-Gm-Message-State: AOAM532aUxtPNjFO0N5ngA3IFUWK9w2gKKzLD+bQgSGzvebH7ZC33Vnd 1seyH5Lfy62Wu1s5luozIEs= X-Google-Smtp-Source: ABdhPJwqwFHziHOjL424gXj48OWUVW9cJhFSWobBgUORi1UQxY7ZSIAUyTAGHUnToOq6IRo0+zeuLw== X-Received: by 2002:a17:90b:8d3:: with SMTP id ds19mr9645749pjb.186.1608919885703; Fri, 25 Dec 2020 10:11:25 -0800 (PST) Received: from [192.168.0.11] (S0106f0f24980d8e3.gv.shawcable.net. [24.108.56.60]) by smtp.gmail.com with ESMTPSA id w31sm30093880pgl.87.2020.12.25.10.11.24 (version=TLS1_3 cipher=TLS_AES_128_GCM_SHA256 bits=128/128); Fri, 25 Dec 2020 10:11:25 -0800 (PST) Content-Type: multipart/alternative; boundary=Apple-Mail-7B0A782C-D595-457E-92D9-CBEF0CF722C9 Content-Transfer-Encoding: 7bit From: Shane Jonas Mime-Version: 1.0 (1.0) Date: Fri, 25 Dec 2020 10:11:23 -0800 Message-Id: References: In-Reply-To: To: Erik Aronesty , Bitcoin Protocol Discussion X-Mailer: iPhone Mail (17G68) X-Mailman-Approved-At: Sat, 26 Dec 2020 03:10:35 +0000 Subject: Re: [bitcoin-dev] BIP Proposal: Wallet Interface X-BeenThere: bitcoin-dev@lists.linuxfoundation.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: Bitcoin Protocol Discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 25 Dec 2020 18:11:31 -0000 --Apple-Mail-7B0A782C-D595-457E-92D9-CBEF0CF722C9 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable There=E2=80=99s a BIP to create a standard API document for the Bitcoin JSON= -RPC API=20 https://github.com/bitcoin/bips/pull/776 here=E2=80=99s an example of the generic ethereum api https://github.com/etc= labscore/ethereum-json-rpc-specification/blob/master/openrpc.json and another example of just the wallet interface https://github.com/etclabsc= ore/signatory/blob/master/openrpc.json here=E2=80=99s a live demo with interactive documentation: https://playground.open-rpc.org/?schemaUrl=3Dhttps://raw.githubusercontent.c= om/etclabscore/ethereum-json-rpc-specification/master/openrpc.json Creating a standard api document like this makes it a lot easier to build de= v tools and documentation. I=E2=80=99d love to help document the bitcoin JSON-RPC API, let me know how I= can help. > On Dec 23, 2020, at 6:15 PM, Erik Aronesty via bitcoin-dev wrote: >=20 > =EF=BB=BFObviously Bitcoin has a wallet api, intermingled with other proto= col APIs: >=20 > https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_calls_list >=20 > 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) >=20 > 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. >=20 > - Erik >=20 >> On Tue, Dec 22, 2020 at 9:48 AM monokh via bitcoin-dev >> wrote: >>=20 >> Hi >>=20 >> 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 tha= t would cover the vast majority of use cases. This can enable writing bitcoi= n applications (e.g. time lock, multi sig) on the web that can be seamlessly= used with any compatible wallets. We have implementations of such examples b= ut I don't want to turn this thread into a promotion and rather focus on the= spec. >>=20 >> Appreciate input from the list. Please share if there are existing effort= s, relevant specs or use cases. >>=20 >> ------------------------------ >>=20 >> A wallet interface specification for bitcoin applications >>=20 >> ## Abstract >>=20 >> This BIP describes an API for Bitcoin wallets and applications as a stand= ard. >>=20 >> ## Summary >>=20 >> Bitcoin wallets should expose their address derivation and signing functi= ons to external applications. The interface would be expressed as follows in= javascript: >>=20 >> ``` >> { >> // Wallet Metadata >> wallet: { >> name: 'Bitcoin Core' >> }, >>=20 >> // Request access to the wallet for the current host >> async enable: (), >>=20 >> // Request addresses and signatures from wallet >> async request ({ method, params }) >> } >> ``` >>=20 >> 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 inten= d to define any standards for how and where the interfaces should be exposed= . >>=20 >> ## Motivation >>=20 >> Due to the seldom available APIs exposed by wallets, applications (web or= otherwise) are limited in how they are able to interact. Generally only sim= ple sends have been available. A more robust API that introduces other reque= sts will promote richer Bitcoin applications. >>=20 >> Additionally, wallet APIs have frequently included inconsistencies in the= ir interfaces and behaviour. This has required applications to build and mai= ntain a separate client for each wallet, increasing the risk of bugs and uni= ntended behaviour as well as being a limiting factor for the adoption of usa= ble bitcoin applications. >>=20 >> With a standardised wallet API: >>=20 >> - 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 >>=20 >> If more wallets implement the specification, applications will be develop= ed more confidently by benefiting from the wallet interoperability. This cre= ates a positive feedback loop. >>=20 >> ## Specification >>=20 >> 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 i= mplemented in other contexts. >>=20 >> ### General Rules >>=20 >> - For sensitive functions (e.g. signing), wallet software should always p= rompt the user for confirmation >>=20 >> ### Types >>=20 >> **UserDeniedError** >> An error type indicating that the application's request has been denied b= y the user >> Type: Error >>=20 >> **Hex** >> Type: String >> Example: `"0000000000000000000a24677957d1e50d70e67c513d220dbe8868c4c3aefc= 08"` >>=20 >> **Address** >> Address details >> Type: Object >> Example: >>=20 >> ``` >> { >> "address": "bc1qn0fqlzamcfuahq6xuujrq08ex7e26agt20gexs", >> "publicKey": "02ad58c0dced71a236f4073c3b6f0ee27dde6fe96978e9a9c9500172e3f= 1886e5a", >> "derivationPath": "84'/1'/0'/0/0" >> } >> ``` >>=20 >> ### API >>=20 >> The wallet must implement the following methods. >>=20 >> **enable** >>=20 >> The enable call prompts the user for access to the wallet. >>=20 >> If successful, it resolves to an address (`**Address**` type) of the wall= et. Typically the first external address to be used as an identity. >>=20 >> **`UserDeniedError`** will be thrown if the request is rejected. >>=20 >> **request** >>=20 >> The request method must take one parameter in the following format: >>=20 >> ``` >> { >> "method": "wallet_methodName", >> "params": ["foo", "bar", "baz"] >> } >> ``` >>=20 >> For a list of mandatory methods see Table >>=20 >> The wallet should reject request calls unless `enable` has been resolved.= >>=20 >> Sensitive requests that involve signing should always prompt the user for= confirmation >>=20 >> On success the request should resolve to the response as defined in the m= ethod table. >>=20 >> **`UserDeniedError`** will be thrown if the request is rejected. >>=20 >> **Mandatory methods** >>=20 >> method: `wallet_getAddresses` params: [`index =3D 0, numAddresses =3D 1, c= hange =3D false`] >> return: `[ Address ]` >> error: UserDeniedError >>=20 >> method: `wallet_signMessage` params: `[ message, address ]` >> return: Signature `Hex` >> error: UserDeniedError >>=20 >> method: `wallet_signPSBT` params: `[ [psbtBase64, inputIndex, address] ]`= >> return: `psbtBase64` >> error: UserDeniedError >>=20 >> method: `wallet_getConnectedNetwork` params: `[]` >> return: Network object `mainnet` | `testnet` | `regetst` >> error: UserDeniedError >>=20 >> ## Rationale >>=20 >> 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 s= uch as node RPC calls. >>=20 >> **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. >>=20 >> **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 do= the rest. Applications should have flexibility in how they implement these f= unctions. It is the role of a library rather than the wallet. >>=20 >> ## Security Implications >>=20 >> Great care should be taken when exposing wallet functionality externally a= s the security and privacy of the user is at risk. >>=20 >> ### Signing >>=20 >> 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 t= ransaction. In the example of a PSBT signature request, the outputs, the inp= uts and which key is being used should be clearly marked. >>=20 >> ### Privacy >>=20 >> 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 pro= tect these behind a confirmation. Commonly the wallet just needs to give the= origin access to all of its public keys, however it could also allow the op= tion to expose only selected derivation paths. >>=20 >> -monokh >>=20 >> _______________________________________________ >> bitcoin-dev mailing list >> bitcoin-dev@lists.linuxfoundation.org >> https://lists.linuxfoundation.org/mailman/listinfo/bitcoin-dev > _______________________________________________ > bitcoin-dev mailing list > bitcoin-dev@lists.linuxfoundation.org > https://lists.linuxfoundation.org/mailman/listinfo/bitcoin-dev --Apple-Mail-7B0A782C-D595-457E-92D9-CBEF0CF722C9 Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: quoted-printable There=E2=80=99s a BIP to create a standard A= PI document for the Bitcoin JSON-RPC API 


and another exampl= e of just the wallet interface https://github.com/etclabscore/signato= ry/blob/master/openrpc.json

here=E2=80=99s a live demo with interactive documentation:


Creating a standard api document like this makes it a lot easier to bu= ild dev tools and documentation.

I=E2=80=99d love to help document the bitcoin JSON-RPC API, let me kno= w how I can help.

On Dec= 23, 2020, at 6:15 PM, Erik Aronesty via bitcoin-dev <bitcoin-dev@lists.l= inuxfoundation.org> wrote:

=EF=BB=BFObviously Bitcoin has a wallet api, in= termingled 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/po= rt to a
local file where the user can grab that token and us= e it (that's
basically how the existing bitcoind does it, wi= th a username/password
living in a file... not as nice as a t= oken/port, IMO)

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

- E= rik

On Tue, Dec 22, 2020 at 9:48 AM monokh v= ia 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 that would cove= r the vast majority of use cases. This can enable writing bitcoin applicatio= ns (e.g. time lock, multi sig) on the web that can be seamlessly used with a= ny compatible wallets. We have implementations of such examples but I don't w= ant to turn this thread into a promotion and rather focus on the spec.

Appreciate input from the list. Please share i= f there are existing efforts, 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 standard.

## Summary

Bitcoin wallets should expose their address derivation and signing functi= ons to external applications. The interface would be expressed as follows in= javascript:
<= br>
```
<= blockquote type=3D"cite">{
// Wallet Metadata
wallet: {
n= ame: 'Bitcoin Core'
}= ,

// Request access to the wallet for the= current host
async e= nable: (),
// Request addresses and signa= tures from wallet
asy= nc request ({ method, params })
}
```

<= blockquote type=3D"cite">In the web context the interface could be exp= osed at the top level of a webpage, for example under `window.bitcoin`. Howe= ver this spec does not intend to define any standards for how and where the i= nterfaces should be exposed.

## Motivatio= n

Due to the seldom available APIs expose= d by wallets, applications (web or otherwise) are limited in how they are ab= le to interact. Generally only simple sends have been available. A more robu= st API that introduces other requests will promote richer Bitcoin applicatio= ns.

Additionally, wallet APIs have freque= ntly included inconsistencies in their interfaces and behaviour. This has re= quired applications to build and maintain a separate client for each wallet,= increasing the risk of bugs and unintended behaviour as well as being a lim= iting factor for the adoption of usable bitcoin applications.

With a standardised wallet API:
=

- Wallets have a clear API to implement
<= blockquote type=3D"cite">- Applications have a clear expectation of wa= llet interface and behaviour
- Applications become agnostic to the wallet specifics, increasing c= hoice for users

If more wallets implement= the specification, applications will be developed more confidently by benef= iting from the wallet interoperability. This creates a positive feedback loo= p.

## Specification

For simplicity, the interface is defined in the context of web a= pplications running in the browser (JS) however, they are simple enough to b= e easily implemented in other contexts.

#= ## General Rules

- For sensitive function= s (e.g. signing), wallet software should always prompt the user for confirma= tion

### Types

**UserDeniedError**
An error type indicating that the application's request has been den= ied by the user
Type:= Error

**Hex**
Type: String
Example: `"0000000000000000000a24677957d1e50d70e67c513d= 220dbe8868c4c3aefc08"`

**Address**=
Address details
<= /blockquote>
Type: Object
Example:

```
{
<= /blockquote>
"address": "bc1qn0fqlzamcfuahq6x= uujrq08ex7e26agt20gexs",
"publicKey": "02ad58c0dced71a236f4073c3b6f0ee27dde6fe96978e9a9c9500172e3= f1886e5a",
"derivatio= nPath": "84'/1'/0'/0/0"
}
```

### API

The wallet= must implement the following methods.

**= enable**

<= /blockquote>
The enable call prompts the user= for access to the wallet.
=
If successful,= it resolves to an address (`**Address**` type) of the wallet. Typically the= first external address to be used as an identity.

**`UserDeniedError`** will be thrown if the request is rejected.

**request**

<= span>The request method must take one parameter in the following format:

=
```
{
"metho= d": "wallet_methodName",
"params": ["foo", "bar", "baz"]
}
```

For a list of mandatory methods see Table

The wallet should reject request calls unl= ess `enable` has been resolved.

Sensitive= requests that involve signing should always prompt the user for confirmatio= n

On success the request should resolve t= o the response as defined in the method table.

= **`UserDeniedError`** will be thrown if the request is rejected.

**Mandatory methods**
<= blockquote type=3D"cite">
method: `wallet_getAddresses` params: [`index =3D 0, numAddresses= =3D 1, change =3D false`]
= return: `[ Address ]`
error: UserDeniedError

method: `wa= llet_signMessage` params: `[ message, address ]`
return: Signature `Hex`
<= blockquote type=3D"cite">error: UserDeniedError

method: `wallet_signPSBT` params: `[ [psbtBase64, inputIndex, a= ddress] ]`
return: `p= sbtBase64`
error: Use= rDeniedError
<= br>
method: `wallet_getConnected= Network` params: `[]`
return: Network object `mainnet` | `testnet` | `regetst`
error: UserDeniedError

## Rationale

The purpo= se of the API is to expose a set of commonly used wallet operations. In addi= tion, it should be flexible enough to serve for other requests such as node R= PC calls.

=
**Why is there a singular reque= st call instead of named methods?**
The transport layer for the requests cannot be assumed, therefo= re it is much more flexible to instead define an abstract format.
=

**Why are the mandatory methods so primitive? Where= is getBalance, getUtxos, ... ?**
A wallet need not worry about providing every possible scenario= for usage. The primitives of keys and signing can expose enough to applicat= ions to do the rest. Applications should have flexibility in how they implem= ent these functions. It is the role of a library rather than the wallet.

=
## Security Implications

Great care should be taken when exposing wallet functionalit= y externally as the security and privacy of the user is at risk.
<= /blockquote>

### Signing

Operati= ons that trigger signing using private keys should be guarded behind confirm= ation screens where the user is fully aware of the nature of the transaction= . In the example of a PSBT signature request, the outputs, the inputs and wh= ich key is being used should be clearly marked.

### Privacy

Some api methods expos= e metadata about the user, such as public keys. Depending on how privacy foc= used the wallet intends to be, the wallet could protect these behind a confi= rmation. Commonly the wallet just needs to give the origin access to all of i= ts public keys, however it could also allow the option to expose only select= ed derivation paths.
=
-monokh

_______________________________________________
bitcoin-dev mailing list
bitcoin-dev@lists.linu= xfoundation.org
https= ://lists.linuxfoundation.org/mailman/listinfo/bitcoin-dev
_______________________________________________
b= itcoin-dev mailing list
bitcoin-dev@lists.linuxfoundation.or= g
https://lists.linuxfoundation.org/mailman/listinfo/bitcoin= -dev
= --Apple-Mail-7B0A782C-D595-457E-92D9-CBEF0CF722C9--