General revamp of the typescript library

[lukasz-zimnoch]

Closes: #698

Here we present a comprehensive refactoring of the tBTC v2 typescript library (a.k.a. typescript SDK). So far, the library was basically a bag of various utility functions, and the responsibility of using them correctly was on the library clients' side. This approach was enough for the first phases of protocol development where the library was used mainly for internal purposes. However, as the protocol becomes more mature, it makes sense to encourage external integrators. This, in turn, requires us to improve the developer experience provided by the SDK and reduce the overhead for users. This pull request aims to achieve that goal.

The initial plan was to open several PRs one after another but, given the fact that #695 was happening simultaneously and had precedence, it was easier to track progress and resolve conflicts within a single pull request. Because of the size, I strongly recommend reviewing commit by commit. The history of changes clearly shows all the steps that were taken. Worth noting that there are very few changes in the logic itself. Most of them are file/directory structure changes, renames, and public API improvements. Here is a detailed description of specific steps:

Rework of the file and directory structure

So far, the file structure of the library was flat and grouped related functions into files like bitcoin.ts or deposit.ts. This quickly led to poor readability and encapsulation. The new approach uses a hierarchical approach dividing code into two distinct categories:

• Shared libraries living under lib directory
• Feature services living under services directory

Shared libraries

This category groups all code components that are used across different features. Specific modules are:

• lib/bitcoin: Contains all interfaces and utilities necessary to interact with the Bitcoin chain
• lib/contracts: Provides chain-agnostic interfaces allowing to interact with tBTC v2 smart contracts
• lib/electrum: Contains an Electrum-based implementation of the Bitcoin client
• lib/ethereum: Provides implementations of tBTC v2 smart contract interfaces for Ethereum chain
• lib/utils: Holds some general utility functions

Each aforementioned module contains an index.ts file that re-exports components from specific sub-modules in order to flatten import paths used by library clients.

Feature services

This category holds services providing access to specific features of the tBTC v2 system:

• services/deposits: Provides access to the tBTC v2 deposit flow for BTC depositors through the DepositsService component
• services/redemptions: Provides access to the tBTC v2 redemption flow for TBTC redeemers through the RedemptionsService component
• services/maintenance: Provides access to authorized maintenance actions for maintainers (e.g. optimistic minting guardians) through the MaintenanceService component

Just as for shared libraries, each module contains an index.ts that re-exports all exported components from specific sub-modules.

Provide a simple entry point with embedded chain configurations

So far, the library has not provided any unified entry point that could be used by external clients. The root index.ts just exported the most important components without any further guidance. Here we aim to change that by introducing the TBTC entry point class. The main purpose of it is to provide some static functions allowing to quickly initialize the SDK and expose specific feature services in a simple way. As for now, the TBTC component can be initialized using the following functions:

• initializeMainnet which initializes the SDK to point tBTC v2 contracts on Ethereum and use mainnet as Bitcoin network
• initializeGoerli which initializes the SDK to point tBTC v2 contracts on Goerli and use testnet as Bitcoin network
• initializeCustom which allows using custom tBTC v2 contracts (e.g. local) and use an arbitrary Bitcoin network (e.g. regtest or simnet)

Once initialized, the TBTC component provides easy access to specific feature services. To address unforeseen needs, it also gives low-level direct access to the underlying tBTC v2 smart contracts and the Bitcoin client:

// Initialize SDK
const signer = (...) 
const sdk = await TBTC.initializeMainnet(signer) 

// Access feature services
sdk.deposits.(...)
sdk.redemptions.(...)

// Access tBTC v2 smart contracts and Bitcoin client directly
sdk.tbtcContracts.bridge.(...)
sdk.bitcoinClient.(...)

Other changes

Apart from the ones mentioned above, there were other important changes that had to be made. First and foremost, this PR integrates bcoin removal done as part of #695. The integration was achieved by applying changes from specific PRs in separate commits here. Secondly, the unit tests file structure was adjusted to reflect the new approach with lib and services top-level directories.

Usage examples

Changes made as part of this work greatly facilitated access to the two core use cases of the tBTC v2 system: depositing and redeeming. Here are some examples of how it looks like now:

// Initialize SDK
const signer = (...) 
const sdk = await TBTC.initializeMainnet(signer) 

// Deposit flow
const bitcoinRecoveryAddress = "" // take this from user input
const deposit = await sdk.deposits.initiateDeposit(bitcoinRecoveryAddress)
const depositAddress = await deposit.getBitcoinAddress() // present that to the user
await deposit.initiateMinting() // this will initiate minting if BTC were sent to the deposit address

// Redemption flow
const bitcoinRedeemerAddress = "" // take this from user input
const amount = "" // take this from user input
await sdk.redemptions.requestRedemption(bitcoinRedeemerAddress, amount)

[nkuba]

What is returned if this line fails? Don't we want to ensure the address is defined and non-empty and throw an error otherwise?

[tomaszslabon]

If the provided publicKey is correct, the address will always be defined and correct.
If the provided publicKey is incorrect (e.g. is empty, the length is incorrect, the prefix is incorrect) this function will throw an error:

  1) Bitcoin
       BitcoinAddressConverter
         publicKeyToAddress
           with testnet addresses
             should return correct P2PKH address for testnet:
     Error: Expected property "pubkey" of type ?isPoint, got Buffer

I'm not sure we need to add any further check on the publicKey, unless we want to have cleaner error messages (i.e. stating exactly what is wrong).
We could add unit tests for the malformed publicKey, though.
But perhaps not in this PR , as it's all about the design.

[lukasz-zimnoch]

Let's add unit tests as part of #714 @tomaszslabon

[tomaszslabon]

@lukasz-zimnoch OK, let's not resolve this comment to keep it as a reminder.

[nkuba]

Same question about what happens when the address geneartion fails?

[tomaszslabon]

If the provided publicKeyHash is incorrect (it's not a hexstring of length 20) the function will throw an error:

  1) Bitcoin
       BitcoinAddressConverter
         publicKeyHashToAddress
           when network is mainnet
             when witness option is false
               when proper public key hash is provided
                 should encode public key hash into bitcoin address properly:
     Error: Expected property "hash" of type Buffer(Length: 20), got Buffer(Length: 19)

So it either succeeds (i.e. the address is defined) or it throws.
We have some unit tests covering incorrect length.
We could replace the string argument with Hex, though.
This will ensure we won't end up with a non-hexstring character, or a string with odd number of characters.

[lukasz-zimnoch]

Let's add hex conversion as part of #713 and unit tests as part of #714

[tomaszslabon]

@lukasz-zimnoch OK, let's not resolve this comment to keep it as a reminder.

[nkuba]

Impressive work! 👏
I'm leaving the first chunk of comments.

[tomaszslabon]

@lukasz-zimnoch
We could update the node version requirement in README.
Similarly here.
We require the node version to be 16 or higher.

[lukasz-zimnoch]

here

Good catch! See 4bdc2a1

[Shadowfiend]

Just like the tiniest niptick here… Do we feel like services is the right term for that folder? Given services is often used to refer to longer-running server-side components (even though it has a broader meaning!), I wonder if simply component might be a term that will result in less confusion long term? I know it's a pretty internal detail, so obviously urgency is rather low, and my conviction is similarly low here—but wanted to mention it because I had a little dissonance when I saw it.

[Shadowfiend]

Oh also, holy hell this is beautiful.

[lukasz-zimnoch]

Just like the tiniest niptick here… Do we feel like services is the right term for that folder? Given services is often used to refer to longer-running server-side components (even though it has a broader meaning!), I wonder if simply component might be a term that will result in less confusion long term? I know it's a pretty internal detail, so obviously urgency is rather low, and my conviction is similarly low here—but wanted to mention it because I had a little dissonance when I saw it.

I was wrapping my head around this for a while as well :D My first take was modules but this is causing a lot of confusion with JavaScript modules. Not sure about components - IMO, it's pretty generic and does not fully reflect that those are components that directly face the SDK client. Totally agree that services is not ideal though. My reasoning was: this is the code that provides specific services for SDK clients, so why not call it just services? If we come up with something better here, I'm totally open to change it. The library is still evolving.

[Shadowfiend]

Yeah I don’t love components either, but in this case it’s generic nature kind of helps with the possibility for confusion.

I feel like there’s a better word kicking around somewhere though, I’ll see if it pops into my head at some point.