There’s a BIP to create a standard API document for the Bitcoin JSON-RPC API https://github.com/bitcoin/bips/pull/776
here’s an example of the generic ethereum api https://github.com/etclabscore/ethereum-json-rpc-specification/blob/master/openrpc.json and another example of just the wallet interface https://github.com/etclabscore/signatory/blob/master/openrpc.json here’s a live demo with interactive documentation: https://playground.open-rpc.org/?schemaUrl=https://raw.githubusercontent.com/etclabscore/ethereum-json-rpc-specification/master/openrpc.json Creating a standard api document like this makes it a lot easier to build dev tools and documentation. I’d 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 > <[email protected]> wrote: > > 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 >> <[email protected]> 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 cover the vast majority of use cases. This can enable writing bitcoin >> 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 >> 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 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 functions >> to external applications. The interface would be expressed as follows in >> 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 >> webpage, for example under `window.bitcoin`. However this spec does not >> intend to define any standards for how and where the interfaces should be >> exposed. >> >> ## 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 >> simple sends have been available. A more robust API that introduces other >> requests will promote richer Bitcoin applications. >> >> Additionally, wallet APIs have frequently included inconsistencies in their >> interfaces and behaviour. This has required applications to build and >> maintain a separate client for each wallet, increasing the risk of bugs and >> unintended 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 developed >> more confidently by benefiting from the wallet interoperability. This >> creates a positive feedback loop. >> >> ## Specification >> >> For simplicity, the interface is defined in the context of web applications >> 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 >> prompt the user for confirmation >> >> ### Types >> >> **UserDeniedError** >> An error type indicating that the application's request has been denied by >> the user >> Type: Error >> >> **Hex** >> Type: String >> Example: `"0000000000000000000a24677957d1e50d70e67c513d220dbe8868c4c3aefc08"` >> >> **Address** >> Address details >> Type: Object >> Example: >> >> ``` >> { >> "address": "bc1qn0fqlzamcfuahq6xuujrq08ex7e26agt20gexs", >> "publicKey": >> "02ad58c0dced71a236f4073c3b6f0ee27dde6fe96978e9a9c9500172e3f1886e5a", >> "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 wallet. >> 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 >> method table. >> >> **`UserDeniedError`** will be thrown if the request is rejected. >> >> **Mandatory methods** >> >> method: `wallet_getAddresses` params: [`index = 0, numAddresses = 1, change >> = 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 >> operations. 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 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 applications to do >> the rest. Applications should have flexibility in how they implement these >> 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 behind >> 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 >> inputs and which key is being used should be clearly marked. >> >> ### Privacy >> >> Some api methods expose metadata about the user, such as public keys. >> Depending on how privacy focused the wallet intends to be, the wallet could >> protect 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 >> option to expose only selected derivation paths. >> >> -monokh >> >> _______________________________________________ >> bitcoin-dev mailing list >> [email protected] >> https://lists.linuxfoundation.org/mailman/listinfo/bitcoin-dev > _______________________________________________ > bitcoin-dev mailing list > [email protected] > https://lists.linuxfoundation.org/mailman/listinfo/bitcoin-dev
_______________________________________________ bitcoin-dev mailing list [email protected] https://lists.linuxfoundation.org/mailman/listinfo/bitcoin-dev
