Unified REST APIs for working with Bitcoin

[nud3l]

Is your feature request related to a problem? Please describe.
Protocols built on top of Bitcoin have various APIs available, but they are early stage and often lack documentation. Moreover, they are not well integrated with existing REST APIs like electrs.

Describe the solution you'd like
A clear and concise description of what you want to happen.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context
Add any other context or screenshots about the feature request here.

[nakul1010]

Jotting down currently known APIs pros & cons for designing the Unified API.

Mempool.space

Link
Pros

• Supports testnet, mainnet, signet.
• Rest APIs are well documented with examples.
• Electrum RPC interface for signet.

Cons

• No mentions of brc20/ordinals getter functions.
• No wallet integration mostly all getter functions.

Blockchain.com

Link

Pros

• Native blockchain info Wallet integration available.
• Almost all the rest of APIs are supported by mempool available.

Cons

• No testnet support

BlockCypher

Link

Pros

• Almost all the rest of APIs are supported by mempool and are available
• Can send raw tx to testnet. BTC testnet3 supported.
• Can be used to inscribe data when sending raw tx. But no doc is available.

Cons

• I didn't like the doc structure.

Unisat

Link
It's a wallet Api.
Pros

• Well-documented APIs for brc20 and other inscriptions.

Cons

• No testnet support yet for some APIs.
• I don't know how they will index testnet ordinals. Currently, the mainnet ordinals and testnet ordinals list are identical.
• Mainnet all ordinals not indexed
• Not free?
• need unisat wallet integration to see the inscription.

Unified API

Link: We need to design. :)

The API should support the following important functionalities

• Should work for mainnet, testnet, regtest.
• Should support most of the getter functions mentioned in mempool.space.
• If we want to support Ordinals
  • Should support creating an inscription and allowing it to be signed through different wallets that support taproot and sigwit.
  • Should support indexer. For local deployment, the dev can run his own indexer. Something like here

References

• ordinals explanation with example
• BRC-20 transaction decoded
• brc20 gitbook
• ordinals inscription
• Bitcoin addresses
• Why Indexer is require?

[nakul1010]

As discussed on Discord, the following methods in electrs should be extended to handle

• Method::GET, brc20_inscription if any brc20 inscription was found in the tx, results will be given out in the form

{ 
  "p": "brc-20",
  "op": "mint",
  "tick": "ordi",
  "amt": "1"
}

• Method::GET, get_inscriptionget inscription id.

---

• Method::GET, asset_trackingget balance of asset on bob. This should be a separate API for this, shouldn't be added in electrs. Conduit already here provides the APIs for this, just need to add it in doc section.

cc: @nud3l and @ns212

[nud3l]

What about all the other APIs, e.g., the ones exposed by unisat to also inscribe BRC20 and ordinals plus the functions around BRC20 lists, holders, history, ...? https://docs.unisat.io/dev/open-api/brc20

I'd like to please have a more extensive proposal from you @nakul1010 @ns212 that covers:

1. The proposed new endpoints
2. The order in which you think those should be implemented

[nakul1010]

I was trying to add the APIs without changing much of the electrum structure and without adding an indexer. But if u want most of the functionality, then an indexer needs to be added.

The following methods in the local environment can be accessible at endpoint http://localhost:3003.

Method::Get inscriptionUtxo/{address}

• get the list of inscribed UTXO by address.
• Output

{

  "data": {
    "utxo": [
      {
        "address": "string",
        "codeType": 0,
        "height": 0,
        "idx": 0,
        "inscriptions": [
          {
            "inscriptionId": "string",
            "inscriptionNumber": 0,
            "isBRC20": true,
          }
        ],
        "satoshi": 10000,
        "scriptPk": "string",
        "scriptType": "string",
        "txid": "string",
      }
    ]
  }
}

---

Method::Get bestheight

• Get the best block height of BRC20 data
• Output

{
  "data": {
    "height": 0,
    "total": 0
  }
}

---

Method::Get /inscriptions/<FROM>

• Get the inscriptions in the given block to the latest block.
• Output

{

  "data": {
    "inscriptions": [
      {
		"inscriptionId": "string",
		"inscriptionNumber": 0,
		"isBRC20": true,
      },
      {
		"inscriptionId": "string",
		"inscriptionNumber": 1,
		"isBRC20": true,
      }
    ]
  }
}

---

Method::Get brc20/list

• Output

{
  "data": {
    "height": 813863,
    "total": 42905,
    "start": 0,
    "detail": [
      "ordi",
      "meme",
      "abcd",
    ]
  }
}

---

Method::Get brc20balance/<address>/<ticker>

• Indexer require for this
• Output

{
  "data": {
    "ticker": "ordi",
    "overallBalance": "644000",
	"historyInscriptions": [
      {
        "data": null,
        "inscriptionNumber": 8196044,
        "inscriptionId": "decd853d761285b772b9dfcb4dc60d05df5cca07c46b5a6d6e9ef9a9f816e20di0",
        "confirmations": 0
      },
      {
        "data": null,
        "inscriptionNumber": 8122019,
        "inscriptionId": "5e79c838aabf8f13c80a504ad0166c6fdc9310568458f63fc0d7d59b32b5afc3i0",
        "confirmations": 0
      },
      {
        "data": null,
        "inscriptionNumber": 8122017,
        "inscriptionId": "a883d254d6c625413e33d68d2c5b73eb78c403d4c0521e7492931cafb5ef7c7fi0",
        "confirmations": 0
      },
      {
        "data": null,
        "inscriptionNumber": 8122018,
        "inscriptionId": "e1a2b505460926764e322f154a814d3624e7d6c33a6172fb94133611f77301a8i0",
        "confirmations": 0
      },
      {
        "data": null,
        "inscriptionNumber": 8196043,
        "inscriptionId": "8380dbaf93ba6b441d12633920d692864dddc8a574fa4818039ad20064ceb451i0",
        "confirmations": 0
      },
      {
        "data": null,
        "inscriptionNumber": 8076373,
        "inscriptionId": "bc00977dbd87fb22f54f5c1b4eba781991243ffefebfbe639db45983246dbfe5i0",
        "confirmations": 0
      },
      {
        "data": null,
        "inscriptionNumber": 8076372,
        "inscriptionId": "9115ce42d15d1ffb878a6af1077bde8a2da765f3e299c3fd915a5b353230a812i0",
        "confirmations": 0
      }
    ]
  }
}

---

Method::Get inscriptions/<address>/<ticker>

• get inscriptions by account
• Output

{
  "code": 0,
  "msg": "ok",
  "data": {
    "cursor": 0,
    "total": 29,
    "totalConfirmed": 29,
    "totalUnconfirmed": 0,
    "totalUnconfirmedSpend": 0,
    "utxo": [
      {
        "txid": "0328b6bb6d749cf2d2535eb5cef939a0f5db5bdf4540b80ff773c3a85888c2bb",
        "satoshi": 546,
        "scriptType": "0020",
        "inscriptions": [
          {
            "inscriptionNumber": 22818979,
            "inscriptionId": "a6cba6a3bd2cde4b7a600638838de5387aeb4f061968fb894f0cf14e0ee3b0edi0",
            "isBRC20": true
          }
        ]
      },
      {
        "txid": "c42584248fb93e0b8e51db8344d53cdaa3eb12e5e73e6ae72d855d23aa1a9b0b",
        "satoshi": 546,
        "inscriptions": [
          {
            "inscriptionNumber": 23338832,
            "inscriptionId": "9774f5827c242962d3f12f599221370f9e9d8b121605e6e29e6a32863717d96ei0",
            "isBRC20": true
          }
        ]
      },
    ]
  }
}

---

• Need to research for the following Post methods in much more depth. But the input/outputs should not change. It will also depend upon user wallet it should support segwit and taproot addresses.

Method::Post create_inscriptions/<address>/<json_string>

{
  "code": 0,
  "msg": "ok",
  "data": {
	"Inscriptions": [
	   {
		   "inscriptionId": "9774f5827c242962d3f12f599221370f9e9d8b121605e6e29e6a32863717d96ei0",
		   "index": 0
	   },
	   {
		   "inscriptionId": "9774f5827c242962d3f12f599221370f9e9d8b121605e6e29e6a32863717d96ei0",
		   "index":1
	   },
	   {
		   "inscriptionId": "9774f5827c242962d3f12f599221370f9e9d8b121605e6e29e6a32863717d96ei0",
		   "index": 2
	   }
	]
  }
}

---

Method::Post create_batch_inscriptions/<address>/<json_string>/

---

Method::Post brc20/deploy/<address>/<amount>

• JSON input

{
  "receiveAddress": "",
  "feeRate": 1,
  "outputValue": 546,
  "devAddress": "",
  "devFee": 0,
  "brc20Ticker": "",
  "brc20Max": "",
  "brc20Limit": ""
}

• JSON Output

{
  "code": 0,
  "msg": "string",
  "data": {
    "amount": 3000,
    "paidAmount": 0,
	"status": "pending",
    "feeRate": 0,
    "minerFee": 0,
    "files": [
      {
        "filename": "10000.sats",
        "inscriptionId": "",
        "status": "pending"
      }
    ]
  }
}

---

Method::Post brc20/transfer/<address>/<amount>

• JSON Input

{
  "receiveAddress": "",
  "feeRate": 1,
  "outputValue": 546,
  "devAddress": "",
  "devFee": 0,
  "brc20Ticker": "",
  "brc20Max": "",
  "brc20Limit": ""
}

• JSON Output

{
  "code": 0,
  "msg": "string",
  "data": {
    "amount": 3000,
	"status": "pending",
    "paidAmount": 0,
    "feeRate": 0,
    "minerFee": 0,
    "files": [
      {
        "filename": "10000.sats",
        "inscriptionId": "",
        "status": "pending"
      }
    ]
  }
}

---

Method::Post brc20/mint/<address>/<amount>

• JSON Input

{
  "receiveAddress": "",
  "feeRate": 1,
  "outputValue": 546,
  "devAddress": "",
  "devFee": 0,
  "brc20Ticker": "",
  "brc20Max": "",
  "brc20Limit": ""
}

• JSON Output

{
  "code": 0,
  "msg": "string",
  "data": {
    "amount": 3000,
    "paidAmount": 0,
	"status": "pending",
    "feeRate": 0,
    "minerFee": 0,
    "files": [
      {
        "filename": "10000.sats",
        "inscriptionId": "",
        "status": "pending"
      }
    ]
  }
}

---

Still Unknowns

• Should work for regtest as electrs will start from the genesis block.
• For testnet and mainnet, if anyone tries to access the getter functions it will fail likely since inscriptions won't be found for historical blocks.
• The unisat APIs are not open source so need to research POST methods.

---

Proposal to implement

ToDos in serial order

• Understanding ord codebase completely.
• Changes in Electrum
  • Add inscription_db: Option<Arc<RwLock<Inscriptions>>> field
  • For every block
    Get Block transactions -> Get witness data -> Parse inscriptions -> Store inscriptions inDB.
  • GET methods
    • For every GET API, lock the <InscriptionDB> field in read-only mode. The <InscriptionDB> field will act as an Indexer.
    • Implementing and testing all getter methods.
  • POST methods
    • Implementing Post methods

[nakul1010]

Closed in #73