Unified REST APIs for working with Bitcoin

nud3l commented 12 months ago

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 commented 11 months ago

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 inmempool.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

nakul1010 commented 11 months ago

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 commented 11 months ago

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:

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

nakul1010 commented 11 months ago

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
```json
{
  "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 commented 11 months ago

Closed in #73

bob-collective / bob