github.com/rumhocker/blockbook@v0.3.2/CONTRIBUTING.md (about)

     1  # Blockbook Contributor Guide
     2  
     3  Blockbook is back-end service for Trezor wallet. Although it is open source, the design and development of the core packages
     4  is done by Trezor developers in order to keep Blockbook compatible with Trezor.
     5  
     6  Bug fixes and support for new coins are welcome. **Please take note that non-fixing pull requests that change base
     7  packages or another coin code will not be accepted.** If you have a need to change some of the existing code, please file
     8  an issue and discuss your request with Blockbook maintainers.
     9  
    10  ## Development environment
    11  
    12  Instructions to set up your development environment and build Blockbook are described in a separate
    13  [document](/docs/build.md).
    14  
    15  ## How can I contribute?
    16  
    17  ### Reporting bugs
    18  
    19  A great way to contribute to the project is to send a detailed report when you encounter an issue. We always appreciate
    20  a well-written, thorough bug report, and will thank you for it!
    21  
    22  Check that [our issue database](https://github.com/trezor/blockbook/issues) doesn't already include that problem or
    23  suggestion before submitting an issue. If you find a match, you can use the "subscribe" button to get notified on
    24  updates. Do not leave random "+1" or "I have this too" comments, as they only clutter the discussion, and don't help
    25  resolving it. However, if you have ways to reproduce the issue or have additional information that may help resolving
    26  the issue, please leave a comment.
    27  
    28  Include information about the Blockbook instance, which is shown at the Blockbook status page or returned by API call. For example execute `curl -k https://<server name>:<public port>/api` to get JSON containing details about Blockbook and Backend installation.  Ports are listed in the [port registry](/docs/ports.md). 
    29  
    30  Also include the steps required to reproduce the problem if possible and applicable. This information will help us
    31  review and fix your issue faster. When sending lengthy log-files, consider posting them as a gist
    32  (https://gist.github.com).
    33  
    34  ### Adding coin support
    35  
    36  > **Important notice**: Although we are happy for support of new coins, we do not have enough capacity to run them all
    37  > on our infrastructure. We run Blockbook instances only for selected number of coins. If you want to have Blockbook
    38  > instance for your coin, you will have to deploy it to your own server.
    39  
    40  Trezor harware wallet supports over 500 coins, see https://trezor.io/coins/. You are free to add support for any of
    41  them to Blockbook. Currently implemented coins are listed [here](/docs/ports.md).
    42  
    43  You should follow the steps below to get smooth merge of your PR.
    44  
    45  #### Add coin definition
    46  
    47  Coin definitions are stored in JSON files in *configs/coins* directory. They are the single source of Blockbook
    48  configuration, Blockbook and back-end package definition and build metadata. Since Blockbook supports only single
    49  coin index per running instance, every coin (including testnet) must have single definition file.
    50  
    51  All options of coin definition are described in [config.md](/docs/config.md).
    52  
    53  Because most of coins are fork of Bitcoin and they have similar way to install and configure their daemon, we use
    54  templates to generate package definition and configuration files during build process. Similarly, there are templates for Blockbook
    55  package. Templates are filled with data from coin definition. Although normally all package definitions are generated automatically
    56  during the build process, sometimes there is a reason to check what was generated. You can create them by calling
    57  `go run build/templates/generate.go coin`, where *coin* is name of definition file without .json extension. Files are
    58  generated to *build/pkg-defs* directory.
    59  
    60  Good examples of coin configuration are
    61  [*configs/coins/bitcoin.json*](configs/coins/bitcoin.json) and
    62  [*configs/coins/ethereum.json*](configs/coins/ethereum.json) for Bitcoin type coins and Ethereum type coins, respectively.
    63  
    64  Usually you have to update only a few options that differ from the Bitcoin definition. At first there is base information
    65  about coin in section *coin* – name, alias etc. Then update port information in *port* section. We keep port series as
    66  listed in [the port registry](/docs/ports.md). Select next port numbers in the series. Port numbers must be unique across all
    67  port definitions.
    68  
    69  In the section *backend* update information how to build and configure back-end service. When back-end package is built,
    70  build process downloads installation archive, verifies and extracts it. How it is done is described in
    71  [build guide](/docs/build.md#on-back-end-building). Naming conventions and versioning are described
    72  also in [build guide](/docs/build.md#on-naming-conventions-and-versioning). You have to update *package_name*,
    73  *package_revision*, *system_user*, *version*, *binary_url*, *verification_type*, *verification_source*,
    74  *extract_command* and *exclude_files*. Also update information whether service runs mainnet or testnet network in
    75  *mainnet* option.
    76  
    77  In the section *blockbook* update information how to build and configure Blockbook service. Usually they are only
    78  *package_name*, *system_user* and *explorer_url* options. Naming conventions are are described
    79  [here](/docs/build.md#on-naming-conventions-and-versioning).
    80  
    81  Update *package_maintainer* and *package_maintainer_email* options in the section *meta*.
    82  
    83  Execute script *go run contrib/scripts/check-and-generate-port-registry.go -w* that checks mandatory ports and
    84  uniqueness of ports and updates registry of ports *docs/ports.md*.
    85  
    86  Now you can try to generate package definitions as described above in order to check outputs.
    87  
    88  #### Add coin implementation
    89  
    90  Coin implementation is stored in *bchain/coins* directory. Each coin must implement interfaces *BlockChain* and
    91  *BlockChainParser* (both defined in [bchain/types.go][/bchain/types.go]) and has registered factory function by
    92  *init()* function of package *blockbook/bchain/coins* ([bchain/coins/blockchain.go](/bchain/coins/blockchain.go)).
    93  
    94  There are several approaches how to implement coin support in Blockbook, please see examples below.
    95  
    96  Bitcoin package *blockbook/bchain/coins/btc* is a reference implementation for Bitcoin-like coins. Most of the functionality
    97  is usually the same so particular coin should embed it and override just different parts.
    98  
    99  Bitcoin uses binary WIRE protocol thus decoding is very fast but require complex parser. Parser translate whole
   100  pubkey-script to database ID and therefore it is usually possible store transactions without change.
   101  
   102  ZCash package *blockbook/bchain/coins/zec* on the other side uses JSON version of RPCs therefore it doesn't require
   103  specialized parser. Only responsibility that parser has is to translate address to Address Descriptor (used as 
   104  address ID in the database) and vice versa.
   105  
   106  Ethereum package *blockbook/bchain/coins/eth* has own stand alone implementation because Ethereum uses totally
   107  different concept than Bitcoin.
   108  
   109  ##### BlockChain interface
   110  
   111  Type that implements *bchain.BlockChain* interface ensures communication with the block chain network. Because
   112  it calls node RPCs, it usually has suffix RPC.
   113  
   114  Initialization of object is separated into two stages. At first there is called factory method (details described
   115  in the next section) and then *bchain.BlockChain.Initialize()* method. Separated initialization method allows you call
   116  inherited methods during initialization. However it is common practice override fields of embedded structure in factory
   117  method.
   118  
   119  Initialization routine usually loads chain information, registers message queue callback and creates mempool
   120  and parser objects.
   121  
   122  BitcoinRPC uses *btc.RPCMarshaller* ([btc/codec.go](/bchain/coins/btc/codec.go)) in order to distinguish API version of
   123  Bitcoin RPC. Current API (*btc.JSONMarshalerV2*) uses JSON object with method arguments. Older API (*btc.JSONMarshalerV1*)
   124  uses JSON array with method arguments and some arguments are defined differently (e.g. bool vs int).
   125  
   126  For example see [zec/zcashrpc.go](/bchain/coins/zec/zcashrpc.go).
   127  
   128  ##### BlockChain factory function
   129  
   130  Factory function must be *coins.blockChainFactory* type ([coins/blockchain.go](/bchain/coins/blockchain.go)). It gets
   131  configuration as JSON object and handler function for PUSH notifications. All factory functions have registered by
   132  *init()* function of package *blockbook/bchain/coins* ([coins/blockchain.go](/bchain/coins/blockchain.go)). Coin name
   133  must correspond to *coin.name* in coin definition file (see above).
   134  
   135  Configuration passed to factory method is coin specific. For types that embed *btc.BitcoinRPC,* configuration must
   136  contain at least fields referred in *btc.Configuration* ([btc/bitcoinrpc.go](/bchain/coins/btc/bitcoinrpc.go)).
   137  
   138  For types that embed base struct it is common practice to call factory method of the embedded type in order to
   139  create & initialize it. It is much more robust than simple struct composition.
   140  
   141  For example see [zec/zcashrpc.go](/bchain/coins/zec/zcashrpc.go).
   142  
   143  ##### BlockChainParser interface
   144  
   145  Type that implements *bchain.BlockChainParser* interface ensures parsing and conversions of block chain data. It is
   146  initialized by *bchain.BlockChain* during initialization.
   147  
   148  There are several groups of methods defined in *bchain.BlockChainParser*:
   149  
   150  * *GetAddrDescFromVout* and *GetAddrDescFromAddress* – Convert transaction addresses to *Address Descriptor* that is used as database ID.
   151    Most of coins use output script as *Address Descriptor*.
   152  * *GetAddressesFromAddrDesc* and *GetScriptFromAddrDesc*  – Convert *Address Descriptor* to addresses and output script. Note that
   153    *btc.BitcoinParser* uses pointer to function *OutputScriptToAddressesFunc* that is called from *GetAddressesFromAddrDesc*
   154    method in order to rewrite implementation by types embedding it.
   155  * *PackTxid* and *UnpackTxid* – Packs txid to store in database and vice versa.
   156  * *ParseTx* and *ParseTxFromJson* – Parse transaction from binary data or JSON and return *bchain.Tx*.
   157  * *PackTx* and *UnpackTx* – Pack transaction to binary data to store in database and vice versa.
   158  * *ParseBlock* – Parse block from binary data and return *bchain.Block*.
   159  
   160  Base type of parsers is *bchain.BaseParser*. It implements method *ParseTxFromJson* that should be the same for all
   161  Bitcoin-like coins. Also implements *PackTx* and *UnpackTx* that pack and unpack transactions using protobuf. Note
   162  that Bitcoin stores transactions in more compact binary format.
   163  
   164  *bchain.BaseParser* stores pointer to function *bchain.AddressFactoryFunc* that is responsible for making human readable
   165  address representation. See [*bch.bcashparser*](/bchain/coins/bch/bcashparser.go) for example of implementation that uses
   166  different approach for address representation than Bitcoin.
   167  
   168  #### Add tests
   169  
   170  Add unit tests and integration tests. **Pull requests without passing tests will not be accepted**. 
   171  How to implement tests is described [here](/docs/testing.md).
   172  
   173  #### Deploy public server
   174  
   175  Deploy Blockbook server on public IP address. Blockbook maintainers will check your implementation before merging.