Skip to content

0005.md

Latest commit

 

History

History
113 lines (90 loc) · 5.33 KB

0005.md

File metadata and controls

113 lines (90 loc) · 5.33 KB
Raw

BRC-5: HTTP Wallet Communications Substrate

Abstract

The Bitcoin Wallet HTTP Interface is a standard interface that enables applications to connect with Bitcoin wallets to facilitate certain functionality. The interface provides a unified way for applications to request the creation of a Bitcoin transaction, encryption, digital signature creation, and other features provided by the wallet. By standardizing the interface, applications can support multiple wallets and give the user greater control over their Bitcoin-related activities.

Motivation

The motivation for this standard interface is to provide a common way for applications to connect with Bitcoin wallets. Currently, many Bitcoin wallets provide their own APIs, which makes it difficult for applications to support multiple wallets. The Bitcoin Wallet HTTP Interface standardizes the way that applications can interact with wallets, enabling them to be more easily integrated into various applications. This interface is designed to be flexible enough to support a range of wallets and use cases, while also providing a secure and standardized method of communication.

Status Note

This document originally described the pre-BRC-100 localhost HTTP API. The /v1/... routes, mixed GET/POST method table, and legacy method names such as createCertificate and findCertificates are historical. Current interoperable implementations in bsv-blockchain/ts-sdk expose the BRC-100 wallet interface over HTTP substrates without a versioned URL prefix.

Implementers SHOULD use the current substrates below for new work. The older route table is deprecated except where a deployment explicitly maintains backwards compatibility with legacy wallets.

Specification

Current wallet HTTP interoperability is defined by two localhost substrates for the BRC-100 wallet interface:

  1. Binary wallet wire

    • Default base URL: http://localhost:3301
    • Route: POST /<BRC-100 methodName>
    • Request body: application/octet-stream
    • Body framing: the BRC-100 wallet-wire parameter payload for the selected method, excluding the method call code and originator frame that are used by the client-side substrate to choose the route and Origin header.
    • Originator: conveyed through the HTTP Origin header when available.

  2. JSON wallet API

    • Default base URL: http://localhost:3321
    • Secure development base URL: https://localhost:2121
    • Route: POST /<BRC-100 methodName>
    • Request body: JSON arguments for the BRC-100 method
    • Response body: JSON result
    • Originator: Node clients may set Origin and Originator; browser clients rely on the browser-managed Origin header.

No /v1 prefix is used by the current ts-sdk HTTP wallet substrates.

Standard HTTP Routes

Every current BRC-100 wallet method is addressed by its method name:

Route Request Method Substrate
/createAction POST Binary wire or JSON
/signAction POST Binary wire or JSON
/abortAction POST Binary wire or JSON
/listActions POST Binary wire or JSON
/internalizeAction POST Binary wire or JSON
/listOutputs POST Binary wire or JSON
/relinquishOutput POST Binary wire or JSON
/getPublicKey POST Binary wire or JSON
/revealCounterpartyKeyLinkage POST Binary wire or JSON
/revealSpecificKeyLinkage POST Binary wire or JSON
/encrypt POST Binary wire or JSON
/decrypt POST Binary wire or JSON
/createHmac POST Binary wire or JSON
/verifyHmac POST Binary wire or JSON
/createSignature POST Binary wire or JSON
/verifySignature POST Binary wire or JSON
/acquireCertificate POST Binary wire or JSON
/listCertificates POST Binary wire or JSON
/proveCertificate POST Binary wire or JSON
/relinquishCertificate POST Binary wire or JSON
/discoverByIdentityKey POST Binary wire or JSON
/discoverByAttributes POST Binary wire or JSON
/isAuthenticated POST Binary wire or JSON
/waitForAuthentication POST Binary wire or JSON
/getHeight POST Binary wire or JSON
/getHeaderForHeight POST Binary wire or JSON
/getNetwork POST Binary wire or JSON
/getVersion POST Binary wire or JSON

The method names, argument structures, result structures, and binary call codes are specified normatively in BRC-100.

JSON Code Example

const httpResult = await makeHttpRequest(
  'http://localhost:3321/createAction',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      description: 'Create a wallet action',
      outputs: []
    })
  }
)

Binary-Wire Code Example

const httpResult = await makeHttpRequest(
  'http://localhost:3301/createAction',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/octet-stream'
    },
    body: walletWireParameterBytes
  }
)

Implementation

Applications and wallets should implement the current BRC-100 method set and one or more of the current HTTP substrates above. The current reference implementation is the bsv-blockchain/ts-sdk wallet substrate implementation.