Skip to content

Latest commit

 

History

History
334 lines (237 loc) · 8.55 KB

README.md

File metadata and controls

334 lines (237 loc) · 8.55 KB
Raw

README

Electrum Proxy Middleware

ExpressJS middleware to add functionality for proxying requests to Electrum servers

Agenda

Web applications can't communicate with electrum servers. This package provide ability to make requests to them.

Requirements

Node >= 7.x

Getting started

npm install @agilie/electrum-proxy-middleware

const electrum = require('@agilie/electrum-proxy-middleware');

app.use(electrum.router);

app.listen(3000)

curl -X GET http://localhost:3000/server/version?coinType=btc
> {"status":"success","result":["ElectrumX 1.13.0","1.4"]}

or

curl -X GET 'http://localhost:3000/server/version?port=55002&host=tn.not.fyi&connectionType=ssl&version=1.4'
> {"status":"success","result":["ElectrumX 1.13.0","1.4"]}

Running the tests

npm test

Supported calls

All calls are required to have a coinType param or at least host, port, connectionType and version params.

Param Value
coinType (required) supported coin types
netMode mainnet(by default) or testnet

or

Param Value
host (required) e.g. tn.not.fyi
port (required) e.g. 55002
connectionType (required) ssl or tcp
version (required) e.g 1.4
netMode mainnet (by default) or testnet

Server methods

[GET] /server/version eq. to server.version

[GET] /server/features eq. to server.features

[GET] /server/banner eq. to server.banner

[GET] /server/donation-address eq. to server.donation_address

[GET] /server/add_peer eq. to server.add_peer

[GET] /server/get-peers eq. to server.peers.subscribe

[GET] /server/ping eq. to server.ping

Example: /server/version?coinType=btc

Blockchain methods

[GET] /block/header eq. to blockchain.block.header

Additional params:

Param Type Description
version Float server version
height non-negative integer the height of the block

Example: /block/header?coinType=btc&height=5

[GET] /block/headers eq. to blockchain.block.headers

Additional params: start_height - the height of the first header requested, count - the number of headers requested.
Example: /block/headers?&coinType=btc&start_height=5&count=1

[GET] /blockchain/estimatefee eq. to blockchain.estimatefee

Additional params:

Param Description
blocks the number of blocks to target for confirmation

Example: /blockchain/estimatefee?coinType=btc&blocks=1

[GET] /blockchain/relayfee eq. to blockchain.relayfee

Example: /blockchain/relayfee?coinType=btc

Mempool methods

[GET] /mempool/get_fee_histogram eq. to mempool.get_fee_histogram

Example: /mempool/get_fee_histogram?coinType=btc

Scripthash methods

Param Type Description
scripthash hexadecimal string script hash

[GET] /scripthash/balance eq. to blockchain.scripthash.get_balance

[GET] /scripthash/listunspent eq. to blockchain.scripthash.listunspent

[GET] /scripthash/get_history eq. to blockchain.scripthash.get_history

[GET] /scripthash/get_mempool eq. to blockchain.scripthash.get_mempool

Example: /scripthash/balance?scripthash=20b360e68b4fe6d1eb460e45434f756fa1582ed687167898f9a716435ecd737f&coinType=btc

Transaction methods

[POST] /transaction/broadcast eq. to blockchain.transaction.broadcast

Additional params:

Param Type Description
raw_tx hexadecimal string raw transaction

[GET] /transaction/get eq. to blockchain.transaction.get

Additional params:

Param Type Description
tx_hash hexadecimal string transaction hash
verbose boolean whether a verbose coin-specific response is required

Example: /transaction/get?tx_hash=871af2528c83ba90bd7b3fbfeac703cbd20f204f1b800ba4ec748842fcac0c9b&coinType=btc

[GET] /transaction/get-merkle eq. to blockchain.transaction.get_merkle

Additional params:

Param Type Description
tx_hash hexadecimal string raw transaction
height integer the height at which it was confirmed

[GET] /transaction/id-from-pos eq. to blockchain.transaction.id_from_pos

Additional params:

Param Type Description
height non-negative integer the main chain block height
tx_pos integer a zero-based index of the transaction in the given block
merkle boolean whether a merkle proof should also be returned

Getting history

Getting history docs.


For more details, refer to the ElectrumX Protocol Methods docs.

Examples

Here are some basic examples.

Protocol version

  • URL

    </server/version?coinType=btc>

  • Method:

    GET

  • URL Params

    Required:

    coinType=[CoinType]

    Optional:

    netMode=[Netmode]

  • Success Response:

    • Code: 200
    • Content:
      {
      "status":"success","result":["ElectrumX 1.13.0","1.4"]
  }

  • Error Response:

    • Code: 409
    • Content:
    {
      "error": [{
          "target": {
              "netMode": "mainnet",
              "coinType": "etc"
          },
          "value": "etc",
          "property": "coinType",
          "children": [],
          "constraints": {
              "isEnum": "coinType must be a valid enum value"
          }
      }]
  }

Or you can specify electrum server:

  • URL

    </server/version?port=55002&host=tn.not.fyi&connectionType=ssl&version=1.4>

  • Method:

    GET

  • URL Params

    Required:

    port=[integer]

    host=[string]

    connectionType=[ssl | tcp]

    version=[server version]

    Optional:

    netMode=[testnet | mainnet]

Confirmed and unconfirmed history of a script hash.

  • URL

    </history/get_history?address=1BWwXJH3q6PRsizBkSGm2Uw4Sz1urZ5sCj&coinType=btc&page=1&pageSize=2>

  • Method:

    GET

  • URL Params

    Required:

    coinType=[CoinType]

    address=[string]

    Optional:

    netMode=[Netmode]

    page=[number]

    pageSize=[number]

  • Success Response:

    • Code: 200
    • Content:
      {
    "status": "success",
    "result": [{
        "value": "0.0002",
        "timestamp": 1399325126000,
        "fee": "0.0001",
        "status": "completed"
    }, {
        "value": "0.00011",
        "timestamp": 1399325126000,
        "fee": "0.0001",
        "status": "completed"
    }],
     "time": 336.57917699999996
  }

  • Error Response:

    • Code: 409
    • Content:
    {
      "error": [{
          "target": {
              "netMode": "test",
              "address": "8b01df4e368ea28f8dc0423bcf77a4923e3a12d307c875e47a0cfbf90b5c39161",
              "coinType": "btc",
              "page": "1",
              "pageSize": "2"
          },
          "value": "test",
          "property": "netMode",
          "children": [],
          "constraints": {
              "isEnum": "netMode must be a valid enum value"
          }
      }]
  }

License

The MIT License (MIT). Full license text is available in LICENSE.