DEV Community: Oghenovo Usiwoma

Elliptic Curve Concepts for Bitcoin Developers

Oghenovo Usiwoma — Sat, 05 Oct 2024 14:22:17 +0000

Elliptic Curve Cryptography (ECC) plays a crucial role in securing digital assets like Bitcoin. Unlike traditional cryptographic methods, ECC provides a high level of security with smaller key sizes, making it more efficient and suitable for modern needs. This article explores the fundamentals of elliptic curves and their properties. By understanding ECC, you gain insight into the backbone of Bitcoin technology.

Definition of Elliptic Curves

An Elliptic Curve is a smooth curve in a two-dimensional plane which consists of the points satisfying the equation:
y^2 = x^3 + ax + b
and a point at infinity. We get different curves by varying the coefficients a,b.


Curves for (a=-1, b=0) and (a=-1, b=1) By GYassineMrabetTalk

Finite Fields

In cryptography, we define the Elliptic Curve over a finite field. This means that the values of x in the curve equation are taken from a special set called a finite field. The Finite Field is a finite set of elements that satisfy the following rules under multiplication, addition, subtraction, and division operations:

Closure: The set is closed under addition and multiplication, meaning that if you add or multiply any two elements in the field, the result is also an element in the field.
Associativity: Addition and multiplication in the field are associative, meaning that the grouping of operations does not change the result. For any elements a, b, and c, this means (a + b) + c = a + (b + c) and (a * b) * c = a * (b * c).
Commutativity: Addition and multiplication are commutative in the field, which means the order of elements does not matter. For any elements a and b, a + b = b + a and a * b = b * a.
Identity Elements:
There is an additive identity (often denoted as 0), which means for any element a, a + 0 = a.
There is a multiplicative identity (often denoted as 1), which means for any element a, a * 1 = a.
Inverses:
For every element a in the field, there is an additive inverse -a such that a + (-a) = 0.
For every non-zero element a, there is a multiplicative inverse a^(-1) such that a * a^(-1) = 1.
Distributivity: Multiplication distributes over addition, meaning for any elements a, b, and c, the equation a * (b + c) = (a * b) + (a * c) holds true.


A plot of an Elliptic Curve over a finite field By Trshaffer

It is a closed system for numbers where we can only use a certain limited set of values. Think of it like the numbers on a clock. If you add 9 hours to 5 o'clock, you get 2 o'clock. This is because, after 12, the numbers "wrap around." A finite field is similar: it has a fixed set of numbers, and whenever an operation exceeds this range, it wraps around, just like on a clock.

Why can't we define the curve over Real Numbers?

We could, but that would make the curve unsuitable for cryptography. Real Numbers are infinite and continuous. We cannot use this for cryptography because we want a finite set of keys, and we want each key to be discrete. Discrete values are easier to represent and operate on in binary.

In ECC, the Public key is a point on the Elliptic curve. It has x and y coordinates which look like real numbers, but they are part of a defined finite field for the curve.

Order of a Finite Field

The order of a set is the number of elements in that set. A Finite field of order n, GF(n), has n elements:
{0, 1, ..., n-1}

Modular Arithmetic

Modular arithmetic is a system of arithmetic for integers, where numbers "wrap around" after reaching a certain value called the modulus. It can be thought of like a clock, where after reaching 12, it wraps around to 1 again. If we have two integers a and n, the modulus n divides a and leaves a remainder r, and we say that r is a modulo n or a mod n:
a≡r (mod n)

We can perform arithmetic operations by finding the result of the operation in mod n. See the following examples:

5 + 4 = 9
9 ≡ 4 (mod 5)
therefore: 5 + 4 ≡ 4 (mod 5)

Simple n-modulo Finite Fields

We can create a finite field using modular arithmetic. An n-modulo finite field is a set of n numbers where all operations like addition, subtraction, multiplication, and division (except by zero) are performed "modulo n"—meaning that the results are taken as the remainder after division by n. An n-modulo finite field, GF(n), where n is a prime number, satisfies the rules of a field defined above. If n is not a prime number, the set will not have multiplicative inverses for all elements which breaks the requirements for a valid field.

The Elliptic Curve Group

A group is a set with a binary operation that satisfies the closure property, associativity, every element in the set has an inverse element and it has an identity element.

The closure property means that passing any two elements of the set, through the group binary operation, will produce a result also in the set. Consider our Finite field above under the addition operator as an example.

Associativity means that in the expression a . b . c where a, b, and c are elements of the group and . is the group operator, it doesn't matter where we put parenthesis so we can freely move it around.
(a . b) . c = a . (b . c)

The identity element, O, of the group is the element that has no effect when applied to another element using the group operator:
a . O = a
For example, in basic addition, 1 + 0 = 1, adding 0 to any real number has no effect. 0 is the identity element for real numbers under addition.

The inverse of an element is its opposite and cancels it out in the group operation:
a . a^-1 = O

The Elliptic Curve points, together with the point at infinity(the identity element) form a group under the addition operator. This allows us to apply other theories from groups to Elliptic Curves. Note that the order of the group does not have to be the order of the finite field. The finite field can have elements that are not on the elliptic curve.

Inverting an Elliptic Curve Point

Given a point, P(x, y), the inverse, -P is (x, -y).

Addition of Elliptic Curve Points

The addition of points in EC is geometrically based. We:

Add two points by drawing a straight line between them and finding the third point where the line intersects the curve then inverting this point. We invert the points to preserve the group axioms of the curve.
When the two points are the same, we draw a tangent to the curve at this point, the inverse of the point where the tangent intersects the curve again is the result.
Adding a point to its inverse results in the point at infinity. This is because the line between P and -P is vertical and will only intersect the curve at the point at inifinity.
Adding a point to the point at infinity results in the original point.


Addition of Elliptic Curve Points By SuperManu

Scalar Multiplication

In linear algebra, a "scalar" is a single number used to "scale" a vector. In the context of Elliptic Curve Group theory, the scalar is a single number that scales a point on the elliptic curve. We do this by adding the point, P to itself n times where n is the scalar. This is represented as n.P or nP.

Elliptic Curve Subgroups

A subgroup is a subset of elements taken from a larger group that itself forms a group under the same operation as the larger group. We can form a subgroup by taking an element, G, of the group and repeatedly scaling that element G until we reach a scalar, n, where:
nG = O (the identity element)
Trying to scale G with n + 1 will return 1G. Hence, there is a "wrap-around" at nG. The scalar n is the order of the subgroup because the subgroup has n elements and scaling beyond n results in elements we have already seen.
A subgroup generated with an element G, contains the following elements:
{O, 1G, 2G, 3G, ..., nG}
This theory applies to Elliptic Curves too. We can create an Elliptic Curve subgroup from a generator point, G, with order n. Note that a subgroup can also contain all the elements of the supergroup.

Elliptic Curve Parameters

We describe an Elliptic Curve Subgroup with the following parameters:

Order of the field, `p`

This refers to the number of elements of the field. Recall from our discussion on Finite Fields that our simple finite field which uses modular arithmetic must have a prime order. Therefore, when choosing the order of the field, it must be a prime number.

Generator Point, `G`

Recall from our discussion on "Elliptic Curve Subgroups", that, by scaling a generator element, we can create a subgroup. The Generator Point, G, is the generator for the elliptic curve subgroup.

Order of the subgroup, `n`

This the number of points in the elliptic curve subgroup. It is the scalar, n, where:
nG = O (identity element)

The Coefficients of the curve, `a`, `b`

Recall the curve equation for elliptic curves:
y^2 = x^3 + ax + b
The coefficients a and b are important parameters that affect the shape of the curve.

The cofactor, h

This is the ratio of the order of the group to the order of the subgroup. It tells you how much bigger the group is than the subgroup. h cannot be less than 1 because this would mean that the subgroup does not fit inside the group. When h is 1, it means that all the elements in the group are in the subgroup. When h is greater than 1, it means there are elements in the group that are not in the subgroup. In EC, for h > 1, we must check that a given point, P is in our desired subgroup before working with it. h = 1 simplifies things and we do not need to check that the point is in our subgroup.

Projected Coordinates

Some implementations of ECC, do not represent the EC point coordinates as (x, y), instead, they may use projected coordinates like the Jacobian system (X, Y, Z, T).
This allows the addition of points in a more efficient way than in affine coordinates.

The secp256k1 Curve

Bitcoin uses the secp256k1 Curve. The parameters are:

p = 2^256 - 2^32 - 2^9 - 2^8 - 2^7 - 2^6 - 2^4 - 1
G = (55066263022277343669578718895168534326250603453777594175500187360389116729240, 32670510020758816978083085130507043184471273380659243275938904335757337482424)
a = 0
b = 7
n = 115792089237316195423570985008687907852837564279074904382605163141518161494337
h = 1

Notice that n is a large prime number. This ensures a large cyclical subgroup and makes it difficult to solve the Discrete Logarithm problem.

Discrete Logarithm Problem

The discrete logarithm problem is like knowing a blender recipe for a smoothie but not being able to figure out the exact ingredients just by tasting it. Imagine you have a secret recipe where you combine a certain number of berries, but after blending, it's hard to reverse-engineer how many berries were used without trying every possibility.

In the case of elliptic curves, if you scale a point, it’s easy to get the new point. But if someone sees the result (the "smoothie") and wants to figure out what number you multiplied by (how many berries you used), it’s incredibly hard to do. This protects our secret keys in cryptography.

For any element, a, in our finite field of order p, GF(p), we can multiply a by itself n times to get a new number x which will be in our field:
x = a^n mod p
But given x and a, it is difficult to find n.
For example, In GF(5) above, we can do:

4^5 (mod 5)
4 * 4 * 4 * 4 * 4 = 1024
1024 / 5 = 204 remainder 4
4^5 = 4 (mod 5)

We can't reverse the operation and find n without checking all the possible values for n. For a large group, the possible values of n are too many, making this problem practically infeasible.

In Elliptic Curves, the problem becomes finding the scalar k such that:
Q = k.P

Secret and Public Keys

We generate pairs of keys in Public Key cryptography. Each key pair contains a public key and a secret key. A public key encrypts a message, producing a Cyphertext that can only be decrypted by the corresponding secret key. The public key can be distributed openly for anyone to use for encryption.

In Elliptic Curve Cryptography, we choose a large random scalar as our secret key, k, and generate a public key by scaling the curve's generator, G, with k. The public key is therefore a point on the curve given by:
K = k.G
With carefully selected curve parameters, we can release K to the public and the secret key, k, will remain secret, thanks to the intractability of the Discrete Logarithm Problem.

In a future article, we will discuss the signatures used in Bitcoin, how they are generated and verified.

Conclusion

In conclusion, elliptic curves provide a powerful mathematical framework for cryptographic applications, especially in systems like Bitcoin. Understanding the group structure, the importance of finite fields, and how elliptic curve points are manipulated through addition and scalar multiplication is crucial to understanding Bitcoin technology and its underlying security mechanisms.

What I missed about BIP143's scriptCode

Oghenovo Usiwoma — Mon, 10 Jul 2023 15:10:54 +0000

I recently tried to create a Transaction to spend from a P2WPKH address. I couldn't get this to work. The sendrawtransaction command kept failing with the error non-mandatory-script-verify-flag (Signature must be zero for failed CHECK(MULTI)SIG operation) (code -26). I narrowed the problem down to incorrectly hashing the sighash. I did not create the sighash as specified by the BIP143 Specification. I'll share my experience navigating this problem here.

A P2WPKH address is Segwit's version of a P2PKH address (See SegWit on Wikipedia). A P2PKH address uses the scriptPubKey shown below:

OP_DUP OP_HASH160 <pubkey_hash> OP_EQUALVERIFY OP_CHECKSIG

It requires the spender to provide the following scriptSig:

<signature> <pubkey>

Here's a good article explaining p2pkh addresses. My (apparently flawed) understanding of P2WPKH was that it does the same thing but with SegWit so I assumed that it had the same scriptPubKey.

Spending from a P2WPKH address requires an ecdsa signature. The message that will be signed is the SigHash. The BIP143 Specification outlined the following items to be serialized into the SigHash:

     1. nVersion of the transaction (4-byte little endian)
     2. hashPrevouts (32-byte hash)
     3. hashSequence (32-byte hash)
     4. outpoint (32-byte hash + 4-byte little endian) 
     5. scriptCode of the input (serialized as scripts inside CTxOuts)
     6. value of the output spent by this input (8-byte little endian)
     7. nSequence of the input (4-byte little endian)
     8. hashOutputs (32-byte hash)
     9. nLocktime of the transaction (4-byte little endian)
    10. sighash type of the signature (4-byte little endian)

I found item 5, the scriptCode of the input to be confusing. I thought this might be referring to the scriptPubKey of the input UTXO but this led to wrong SigHash messages and wrong signatures, hence, my transactions were rejected. After hours of debugging, I discovered that further down in BIP143, there is a section that specifies what the scriptCode is for spending from a P2WPKH address, shown below.

For P2WPKH witness program, the scriptCode is 0x1976a914{20-byte-pubkey-hash}88ac.

0x19 indicates the number of bytes in the script. 0x19 is 25 in decimal. This indicates that the script has 25 bytes.
0x76a9 is code for OP_DUP OP_HASH160.
0x14 is 20 in decimal and it is interpreted as OP_PUSHBYTES20 which pushes the next 20 bytes into the stack.
0x88ac is code for OP_EQUALVERIFY OP_CHECKSIG.
See the analysis of a Transaction with a similar output here.

The scriptCode seemed to be the P2WPKH address scriptPubKey, but the signatures were wrong, why?

After logging the actual utxo.scriptPubKey, I discovered that it was:

OP_0 OP_PUSHBYTES_20 <pubkey_hash>

This wasn't what I expected. I had forgotten something crucial about P2WPKH. SegWit only requires that you specify the segwit version, which is 0 in this case and the 20-byte pubkey_hash. See the P2WPKH section on BIP141. This is called a forwarding script. See this excerpt from bip-tx-terminology:

forwarding script
[Concept] A collective term for scripts that redirect input validation to another script or data structure. Witness programs and P2SH Programs are forwarding scripts. Forwarding scripts make use of script templates that imply additional evaluation steps beyond the explicitly expressed conditions. In the case of P2SH, the output script in verbatim only implies that the redeem script must be the preimage of the hash in the output script, but the template prescribes that the redeem script must additionally be satisfied. For witness programs, the output script is even less verbose with more implied meaning.

DISCLAIMER: This terminology is still pending and it's not widely used yet. See https://github.com/Xekyo/bips/pull/1

The nodes in the Bitcoin network understand that this scriptPubKey is a Segwit_v0_P2WPKH scriptPubKey and they know the script template to use. All I had to do was create a new script following the scriptCode template and use that to make my sighash.

In Rust, using the bitcoin crate, the scriptCode and sighash can be made like this:

let script_code = bitcoin::script::Builder::new()
        .push_opcode(OP_DUP)
        .push_opcode(OP_HASH160)
        .push_slice(&pub_key.wpubkey_hash().unwrap())
        .push_opcode(OP_EQUALVERIFY)
        .push_opcode(OP_CHECKSIG)
        .into_script();

let message = SighashCache::new(unsigned_tx)
        .segwit_signature_hash(input_index, script_code, value, sighash_type);

The Bitcoin crate also provides a function to do this for you.

let mut sighash = SighashCache::new(unsigned_tx);
let (message, _) = psbt.sighash_ecdsa(0, &mut sighash).unwrap();

Conclusion

While the scriptCode looks like it should be the scriptPubKey for P2PWPKH addresses, it is not. P2WPKH uses a forwarding script specified by BIP141 and the actual scriptCode must be constructed using the defined script template.

The PSBT Standard

Oghenovo Usiwoma — Mon, 29 May 2023 06:27:57 +0000

PSBT is short for Partially Signed Bitcoin Transaction. It is a standard for defining transactions that can be signed by multiple signers across different clients. It contains the necessary information for a signer to produce a signature for a transaction. This is specifically beneficial for offline signers as they cannot fetch additional information about a transaction. The original PSBT format was specified in BIP 174 and a Version 2 in progress in BIP 370.

The PSBT Binary format

The PSBT format consists of key-value maps separated by a 0x00 byte. It supports the following maps:

The Global Map contains key-value pairs that apply to the entire transaction
The Input Map contains key-value pairs that apply to individual inputs
The Output Map contains key-value pairs that apply to individual outputs

Key-value pairs in each map all follow this format:

<keylen> <keytype> <keydata> <valuelen> <valuedata>

The keylen, keytype and valuelen are specified as a compact size unsigned integer which ensures values that can be specified in one byte will be specified in one byte, for example, the decimal number ten is specified as 0x0a instead of 0x000a.

keydata is not always available. Some key types like PSBT_GLOBAL_UNSIGNED_TX = 0x00 do not have keydata.

To see the full list of key types supported, go to BIP 174.

Let's look at a few examples:

We'll start by breaking down this PSBT which is an unsigned tx with 0 inputs and 0 outputs.

70736274ff01000a0000000000000000000000

<magic> 0x70736274ff // used to identify PSBT data
<global-map> // contains global transaction data
<keylen> 0x01 // Key length is one byte
<keytype> 0x00 // PSBT_GLOBAL_UNSIGNED_TX
<valuelen> 0x0a // 10 bytes
<valuedata> 0x00000000000000000000 // The Tx hex
<separator> 0x00

Let's breakdown another simple unsigned PSBT data with 1 input and 1 output

0x70736274ff0100550200000001eb63366191dbaf74d30c6de8cbb7208de3fb65ad266b41c56990a5a7e6a2eac90000000000ffffffff010017a804000000001976a914c1752bf5bffbd320ab2ab625b32b9fe48337dce488ac00000000000000

<magic> 0x70736274ff
<global-map>
<keylen> 0x01 // Key length is one byte
<keytype> 0x00 // PSBT_GLOBAL_UNSIGNED_TX
<valuelen> 0x55 // 85 bytes
<valuedata> 0x0200000001eb63366191dbaf74d30c6de8cbb7208de3fb65ad266b41c56990a5a7e6a2eac90000000000ffffffff010017a804000000001976a914c1752bf5bffbd320ab2ab625b32b9fe48337dce488ac00000000 // The Unsigned Tx hex
<separator> 0x00
<input-map>
<separator> 0x00
<output-map>
<separator> 0x00

Signing a PSBT

The Signer uses the UTXOs provided in the PSBT to produce signatures for inputs. The signer performs some checks before signing.

For non-witness inputs, the signer verifies that the txid of the non-witness utxo matches the txid specified in the unsigned transaction.
For witness-inputs, the signer verifies that the witnessScript (if provided) matches the hash specified in the UTXO or the redeemScript, and the redeemScript (if provided) matches the hash in the UTXO

Any signatures created by the Signer must be added as a PSBT_IN_PARTIAL_SIG = 0x02 key-value pair for the respective input it relates to. If a Signer cannot sign a transaction, it must not add a Partial Signature.

Our previous PSBT spends from a non-witness utxo. Before we sign it, we must add the PSBT_IN_NON_WITNESS_UTXO = 0x00 key-value pair for that input:

0100b6020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402bd0300ffffffff02c817a804000000002321035b4a568361af71783c22a6c9d9a13e3d5f32d9a7278c0e8325e4bc29b0090825ac0000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf9012000000000000000000000000000000000000000000000000000000000000000000000000000

The global map is unchanged but new data has been added to the input map:

<input map>
<keylen> 0x01 // 1 byte
<keytype> 0x00 // PSBT_IN_NON_WITNESS_UTXO, requires no keydata
<valuelen> 0xb6 // 182 bytes
<valuedata> // the transaction in network serialization format the current input spends from
0x020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402bd0300ffffffff02c817a804000000002321035b4a568361af71783c22a6c9d9a13e3d5f32d9a7278c0e8325e4bc29b0090825ac0000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000
<separator> 0x00

To sign, we add the following PSBT_IN_PARTIAL_SIG = 0x02 key-value pair to the input pair:

<keylen> 0x22 //
<keytype> 0x02 // PSBT_IN_PARTIAL_SIG keytype
<keydata> 0x035b4a568361af71783c22a6c9d9a13e3d5f32d9a7278c0e8325e4bc29b0090825
<valuelen> 0x47
<valuedata>
3044022063179cb0f91d2b1d2c45d8112a527e4491ec771befb62c5717afac69f42345d9022035b3c00d8cb2f6309e0c0f6df03f54ae3e0bd6c4cae68061a714b57cf4f8cd8c01

Finalizing a PSBT

The Finalizer validates each input, removes the partial sigs and constructs the PSBT_IN_FINAL_SCRIPTSIG = 0x07 and PSBT_IN_FINAL_SCRIPTWITNESS = 0x08 for each input and places them in the Input Map.

Our finalized PSBT looks like this:

0x70736274ff0100550200000001eb63366191dbaf74d30c6de8cbb7208de3fb65ad266b41c56990a5a7e6a2eac90000000000ffffffff010017a804000000001976a914c1752bf5bffbd320ab2ab625b32b9fe48337dce488ac0000000000
// Global map is unchanged

0100b6020000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff0402bd0300ffffffff02c817a804000000002321035b4a568361af71783c22a6c9d9a13e3d5f32d9a7278c0e8325e4bc29b0090825ac0000000000000000266a24aa21a9ede2f61c3f71d1defd3fa999dfa36953755c690689799962b48bebd836974e8cf90120000000000000000000000000000000000000000000000000000000000000000000000000
// PSBT_IN_NON_WITNESS_UTXO is unchanged

// PSBT_IN_PARTIAL_SIG has been removed

<keylen> 0x01
<keyvalue> 0x07 // PSBT_IN_FINAL_SCRIPT_SIG
<valuelen> 0x48
<value> 0x473044022063179cb0f91d2b1d2c45d8112a527e4491ec771befb62c5717afac69f42345d9022035b3c00d8cb2f6309e0c0f6df03f54ae3e0bd6c4cae68061a714b57cf4f8cd8c01
0000

Extracting a serialized transaction

The Extractor uses the unsigned transactions and signatures provided in the PSBT to construct a serialized transaction.

Conclusion

The PSBT standard is a key innovation in the world of Bitcoin transactions. We have only scratched its surface, if you want to read the full specification, go to BIP 174.

NodeJS Stream Processing: Build a Simple multipart/form-data parser

Oghenovo Usiwoma — Wed, 03 May 2023 06:40:11 +0000

TLDR: I build a simple multipart/form-data parser in TypeScript to demonstrate how stream processing works. You can checkout the github repo here

Streams are integral to Node.js, empowering developers to handle data in a more resource-efficient and scalable manner. In essence, a stream is an abstract interface within Node.js designed for the management of streaming data. It offers a mechanism for reading or writing data progressively over a certain period, instead of loading all data simultaneously into memory. This makes streams instrumental in efficiently processing massive data volumes without obstructing the event loop or overwhelming the memory. Node.js features four distinct stream types: Readable, Writable, Duplex, and Transform. Each stream type is equipped with its unique set of methods and events for seamless streaming data manipulation.

The NodeJS http.IncomingMessage extends stream.Readable which means we can read incoming request data using the Readable stream API. We can read data calling its "read" method or listening for its "data" event. We will be using through2 to transform this IncomingMessage stream into one that outputs the form data.

The multipart/form-data format

"Multipart" refers to a type of message that contains multiple parts of pieces of data that are combined into a single message. HTTP clients use the media type "multipart/form-data" to send
files and data to an HTTP Server.

Each part of the multipart message is separated by a boundary. The boundary is a string of characters, and it is provided by the HTTP client in the content-type header.

See an example of a multipart/form-data request:

POST /upload HTTP/1.1
Host: reqbin.com
Content-Type: multipart/form-data; boundary=0000
Content-Length: 526

--0000
Content-Disposition: form-data; name="username"

[Username]
--0000
Content-Disposition: form-data; name="file"; filename="image1.jpg"
Content-Type: image/jpeg

[image data]
--0000
Content-Disposition: form-data; name="file"; filename="image2.jpg"
Content-Type: image/jpeg

[image data]
--0000--

In our case, each part of the multipart message is a field from a form. The Content Disposition header gives us information about the field. We can identify file-type fields by checking for a filename in the disposition header.

The plan

Extracting fields from the request stream is way harder than it seems (at least to me it was). There are some key ideas that I employed to eventually achieve this.

Split data processing into multiple stages

Trying to identify the field boundaries and then processing each field data at the same time was difficult. I couldn't get it working perfectly.
In contrast, separating the problem into:

identifying field boundaries
parsing field data was surprisingly easy. I decided to implement this as two different streams:
The first stream detects field boundaries, collects the data between the boundaries and outputs that data
The second stream processes the field data and outputs a Javascript object. I used through2 to create the two streams and combine them into one "form" stream. ### Sliding Windows Detecting boundary and new line characters required another breakthrough. The input stream provides data in chunks. A chunk of data is an array of bytes. In each chunk, you may have partial or full boundary or new line characters. To reliably detect these strings of characters, I slide each character in each chunk through a buffer of length n from the right. Eventually, the buffer will get full and the oldest character in the buffer will be shifted out for the next character.

After I shift the buffer left for each new character, I compare the contents of the buffer to see if it matches my target string

This acts like a sliding window for detecting strings of characters of length, n. See a pseudo code below;

boundary = 'boudary...chars...'
slidingBuffer = createFixedLengthBuffer(boudary.length)
stream.on((chunk) => {
  data = []
  for (byte in chunk) {
     shiftedOutChar = shiftLeft(slidingBuffer, byte)
     data.push(shiftedOutChar)
     if (equals(slidingBuffer, boundary)) {
       // Boundary detected
     }
  }
})

The Implementation

Let's create a quick http server to receive our multipart/form-data request.

import http from 'http';
import { createFormStream } from './create-form-stream';
import { Field } from './Field';

interface IMakeServerProps {
    onText: (data: Field) => void;
    onFile: (data: Field) => void;
}

export function makeServer({
    onText,
    onFile
}: IMakeServerProps) {
    const server = http.createServer();

    server.on('request', (request, res) => {
        const contentType = request.headers['content-type'];
        const method = request.method;

        if (method?.toLowerCase() !== 'post') {
            res.writeHead(405);
            res.end("Method Not Allowed");
            return;
        }

        if (!contentType?.startsWith('multipart/form-data')) {
            res.writeHead(415);
            res.end("Unsupported Media Type");
            return;
        }

        const boundary = contentType.split("boundary=")[1]?.split(";")[0]; // Extract boundary characters

        const form = createFormStream(request, Buffer.from("--" + boundary));
        form.on('data', (field: Field) => {
            if (field.type === 'text') onText(field);
            if (field.type === 'file') onFile(field);
        });
        form.on('end', () => {
            res.writeHead(200);
            res.end();
        });
    });

    return {
        server
    }
}

In create-form-stream.ts, we define the createFormStream(stream, boundary) which starts by defining some buffers that we will need:

let boundarySlidingBuffer = Buffer.alloc(boundary.length);
let fieldBuffer = Buffer.alloc(0);

We create our first stream to output each field data in one chunk:

return stream
        .pipe(
            through2(function (chunk, _enc, callback) {
                // Detect boundaries and output each field chunk
                let data: Buffer;
                for (let i = 0; i < chunk.length; i++) {
                    data = shiftLeft(boundarySlidingBuffer, chunk[i]); // Shift into our sliding buffer
                    fieldBuffer = Buffer.concat([fieldBuffer, data]); // Concat shifted out data with existing field data in fieldBuffer
                    if (boundarySlidingBuffer.compare(boundary) === 0) {
                        // Boundary detected
                        // Remove "\r\n" from the beginning and end then push
                        this.push(fieldBuffer.subarray(2, -2));
                        fieldBuffer = Buffer.alloc(0); // Clear fieldBuffer
                        boundarySlidingBuffer = Buffer.alloc(boundary.length); // Clear sliding buffer
                    }
                }
                callback();
            })
        )

The second stream processes each field data chunk:

      .pipe(
            through2.obj(function (chunk, _enc, callback) {
                const lines: string[] = [];
                let dataStartIndex = 0;

                const newLine = Buffer.from("\r\n");
                let newLineSlidingBuffer = Buffer.alloc(newLine.length);
                let line = Buffer.alloc(0);
                let data: Buffer;
                for (let i = 0; i < chunk.length; i++) {
                    data = shiftLeft(newLineSlidingBuffer, chunk[i]);
                    line = Buffer.concat([line, data]);
                    if (newLineSlidingBuffer.compare(newLine) === 0) {
                        // New line detected
                        lines.push(line.toString());
                        if (lines[lines.length - 1] === '') {
                            // Break at first empty line. Time for data!
                            dataStartIndex = i + 1;
                            break;
                        }

                        line = Buffer.alloc(0);
                        newLineSlidingBuffer = Buffer.alloc(newLine.length);
                    }
                }

                const builder = new FieldBuilder();

                const disposition = parseDisposition(lines[0]);
                builder
                    .name(disposition.name)
                    .filename(disposition.filename);

                if (lines[1] !== '') {
                    const contentType = parseContentType(lines[1]);
                    builder.contentType(contentType);
                }

                this.push(
                    builder
                        .content(chunk.subarray(dataStartIndex))
                        .build()
                );

                callback();
            })
        );

Conclusion

I hope that this article has given you a better understanding of how to work with streams in Node.js and how your favorite multipart/form-data parser library works.
The code for this article can be found here.

Introduction to Miniscript

Oghenovo Usiwoma — Wed, 03 May 2023 06:06:44 +0000

Miniscript is a representation for Bitcoin scripts that allows composition, analysis, and compilation from spending policies. It has a structure that enables various properties such as correctness, security, and malleability. It translates into Bitcoin Script, the language used to specify spending conditions on the Bitcoin network.

Miniscript offers benefits over the traditional Bitcoin scripting language:

It allows developers to create complex Bitcoin transactions without having to write custom scripts from scratch. This can save developers a lot of time and effort, and also reduce the risk of errors in the code.
It uses a simpler and more predictable syntax that makes it easier to audit and verify the code. This can help reduce the risk of bugs and vulnerabilities in the code, which can help improve the overall security of Bitcoin transactions.

This article assumes that you have an understanding of the Bitcoin Scripting language, that you understand how it uses the Stack and that you are familiar with the major opcodes.

Policies and Fragments

Miniscript policies are written in the Miniscript Policy language, they specify spending conditions for Bitcoin Transaction Outputs. Miniscript policies are made up of fragments, which are building blocks that can be combined to create more complex policies.
These polices are compiled into Miniscript which is then compiled into Bitcoin Script.

To create a simple pay-to-pubkey script in Miniscript policy language, you can use the pk(key) fragment. This fragment allows you to create an output that can only be spent by the owner of the specified public key (pk). The pk(key) policy compiles into pk(key) in Miniscript which compiles into <key> OP_CHECKSIG in Bitcoin Script. This was a simple scenario where the policy language and miniscript script are the same but as we will see, this is not always the case.

Some of the most commonly used Miniscript fragments include:

0: This fragment resolves to 0 in Bitcoin script.
1: This fragment resolves to 1 in Bitcoin script.
pk(key): This fragment allows you to create an output that can only be spent by the owner of the specified public key (pk).
pkh(key): This fragment allows you to create an output that can only be spent by the owner of the private key associated with the specified public key hash (pkh).
older(n): This fragment allows you to create an output that can only be spent after a certain number of blocks have been mined (n).
after(n): This fragment allows you to create an output that can only be spent after a certain date and time (n).
hash160(h): This fragment allows you to create an output that can only be spent by providing a signature that hashes to the specified hash value (h).
and_b(x, y): This fragment allows you to create an output that can only be spent if both x and y are satisfied.
or_b(x, y): This fragment allows you to create an output that can be spent if either x or y is satisfied.
thresh(k, pol_1,…, pol_n): This fragment allows you to create an output that can only be spent if k of the n policies are satisfied.
multi(k, key_1, …, key_n): This fragment allows you to create an output that can only be spent if k of the n specified public keys (keys) sign the transaction.

These fragments can be combined in various ways to create more complex spending conditions for Bitcoin transactions. See the full list of fragments here

Let's create a policy that allows an output to be spent by key1 or key2. We use the or_b and pk(key) fragments to achieve this:

or_b(pk(key1),pk(key2))

This Miniscript policy compiles to
or_b(pk(key_1),s:pk(key_2))
in Miniscript which is
<key_1> OP_CHECKSIG OP_SWAP <key_2> OP_CHECKSIG OP_BOOLOR
in Bitcoin Script.

This will create an output that can be spent by providing a signature that matches either of the specified public keys (key1 or key2). The signature would be verified against the public key using the OP_CHECKSIG opcode.

Let's take a look at a slightly more complicated policy: thresh(3,pk(key_1),pk(key_2),pk(key_3),older(12960))

It compiles into:
thresh(3,pk(key_1),s:pk(key_2),s:pk(key_3),sln:older(12960))
in Miniscript.

This policy specifies a spending condition that requires 3 signatures before 90 days but only require 2 signatures subsequently. It is a 3-of-3 multisig that turns into a 2-of-3 multisig after 90 days.

Here’s a breakdown of how this policy works:

The “thresh” fragment specifies that at least 3 of the specified conditions must be satisfied to spend the output.
The “pk” fragments specify the public keys that can be used to spend the output.
The “older” fragment specifies that after 12960 blocks (about 90 days), the script will change to a 2-of-3 multisig.
Before 90 days, the older(12960) policy cannot be satisfied, hence, you need the signatures for key_1, key_2 and key_3 to meet the thresh requirement.
After 90 days, the older(12960) policy is satisfied and you only need two signatures to meet the thresh requirement.

https://bitcoin.sipa.be/miniscript/ has a Miniscript policy to Miniscript compiler. It also shows the resulting Bitcoin Script.

The Miniscript Type System

Miniscript uses a type system to ensure that the scripts are safe and secure to use. The type system enables static analysis and runtime checks that ensure the scripts are well-formed and that they do not contain any errors or vulnerabilities.

There are four basic types:

"B" B-type expressions are "Base Expressions". They push a nonzero value onto the stack when satisfied and exact zero when dissatisfied.
"V" V-type expressions are "Verify Expressions". They abort script execution when dissatisfied but do no push any value to the stack when satisfied.
"K" K-type expressions are "Key Expressions". They take inputs from the top of the stack, and they push a key onto the stack. A signature is still required to satisfy the expression.
"W" W-type expressions are "Wrapped Expressions". They take inputs from one below the top of the stack. They push their result either on top of the stack or one below. In case of satisfaction, they push a nonzero value and a zero value in case of dissatisfaction.

Apart from the basic types, there are also type modifiers: z, o, n, d and u. Each of them guarantees additional properties, for example:

Type Bz describes an expression that pushes a nonzero value to the stack when satisfied and a zero otherwise because it is a Base expression but it also consumes exactly zero elements because it has the "z" modifier.

An expression can be converted from one type to another by applying wrappers. Wrappers look like this v: and they are applied to expressions like this:
v:<Expression>

There are rules that specify what wrappers can be applied to what expression types and what the type of the resulting expression will be. For example;

v: can only be applied to an expression of type "B" and the resulting expression will have a type "V". Observe:

v:older(n) is valid because older(n) is a "B" expression.
older(n) compiles to <n> OP_CHECKSEQUENCEVERIFY but
v:older(n) compiles to <n> OP_CHECKSEQUENCEVERIFY OP_VERIFY

You can also combine wrappers like this:
dv:older(n)
The d: wrapper is applied to the v: wrapper which is applied to the older(n) fragment.

The v: wrapper converts older(n) to a "V" type
The d: wrapper converts v:older(n) to a "B" type Hence the type of the resulting expression is "B".

This page also has the complete list of wrappers, their requirements, types and properties.

Conclusion

In conclusion, Miniscript is a powerful scripting language that allows for complex Bitcoin transactions to be created with ease. It's simple syntax and modular design make it easy to use and understand, even for those who are new to Bitcoin scripting. Additionally, Miniscript’s flexibility and extensibility make it a great choice for developers who want to create custom Bitcoin transactions that meet their specific needs.

Minimalizing Witness weight for Taproot spend script paths with Huffman's Algorithm

Oghenovo Usiwoma — Sun, 26 Mar 2023 05:54:22 +0000

TLDR

I implement a Huffman Taptree constructor in Typescript for Bitcoinjs-lib. Find the code here.

Introduction

Taproot is a recent upgrade to Bitcoin that enhances the privacy and efficiency of complex transactions by introducing a new type of output that can be spent either by providing a signature for the public key (keypath spend) or by satisfying a script contained within the hidden "script-tree". A script-tree is a kind of Merkle tree that encodes a hierarchy of scripts that represent different spending scenarios, each with a unique path from the root. Spending any of these scripts requires a proof that the script is present in the tree. The length of the proof depends on the position of the script in the tree. Longer proofs incur more transaction fees because they create larger transactions.

One way to reduce transaction fees is to arrange your script-tree such that the scripts that are more likely to be used for spending, require shorter proof. These scripts need to be closer to the root of the tree. We can use Huffman's Algorithm to arrange the script-tree so that the most likely or frequent spend paths are shorter and incur less transaction fees.

Bitcoinops' Schnorr Taproot workshop has a great section on "Huffman TapTree Constructors". I'll show how to implement this in Typescript for bitcoinjs-lib. You can find the github repo for this article, here.

What we are trying to minimize is the Expected-witness-weight:

Expected-witness-weight =
      Probability-of-A * Witness-weight-A
    + Probability-of-B * Witness-weight-B
    + Probability-of-C * Witness-weight-C

We can minimize the expected witness weight by putting those scripts with higher probability closer to the root of the tree.

The Method

Suppose we have three spend scripts represented by A, B and C. We determine that B is twice as likely to be spent as A and C, so we assign the scripts the following weights:
A: 1, B: 2, C: 1

We want to arrange our script-tree such that B is much closer to the root than A and C. We will use Huffman's algorithm and take the following steps:

Sort the scripts A, B and C by weight in ascending order and put them in a queue.
Pick the first two nodes in the queue and create a new branch from the two of them. Set the weight of this new node to be the sum of the weights of its children.
Put this new node back into the queue with sorting order maintained. That is, we must find the correct position for the new node given its weight and put it there.
Repeat steps 2 and 3 until there's only one node left in the queue. This node is the root node for the script-tree.

Implementation

Let's define types to be used in the implementation.

import { Tapleaf, Taptree } from "bitcoinjs-lib/src/types";

export type Inputs = { weight: number, leaf: Tapleaf }[];
export type Node = {
    weight: number,
    node: Taptree
}

We use bitcoinjs-lib's Tapleaf and Taptree because we want to be able to use our resulting script-tree with bitcoinjs-lib.

This is our function definition

function sortScriptsIntoTree(inputs: Inputs): Taptree | undefined {}

Step 1

Create a sorted list of nodes from our inputs.

const nodes: Node[] = inputs
    .map((value) => ({
        weight: value.weight,
        node: value.leaf
    }));

const sortedNodes = new SortedList(
    nodes,
    (a, b) => a.weight - b.weight
); // Create a list sorted in ascending order of frequency

I've created a SortedList class to handle creating and maintaining a sorted list. See the code, here.

Step 2

Pick the first two nodes in the queue and create a new branch from the two of them. Set the weight of this new node to be the sum of the weights of its children.

// Construct a new node from the two nodes with the least frequency
nodeA = sortedNodes.pop()!; // There will always be an element to pop
nodeB = sortedNodes.pop()!; // because loop ends when length <= 1
newNode = {
    weight: nodeA.weight + nodeB.weight,
    node: [nodeA.node, nodeB.node]
};

Step 3

Put this new node back into the queue with sorting order maintained. That is, we must find the correct position for the new node given its weight and put it there.

sortedNodes.insert(newNode);

The SortedList class will use binary search to find the correct index for the new node in the sorted list

Step 4

Repeat steps 2 and 3 until there's only one node left in the queue. This node is the root node for the script-tree.

let newNode: Node;
let nodeA: Node, nodeB: Node;
while (sortedNodes.length() > 1) {
    // Construct a new node from the two nodes with the least frequency
    nodeA = sortedNodes.pop()!; // There will always be an element to pop
    nodeB = sortedNodes.pop()!; // because loop ends when length <= 1
    newNode = {
        weight: nodeA.weight + nodeB.weight,
        node: [nodeA.node, nodeB.node]
    };
    // Place newNode back into sorted list
    sortedNodes.insert(newNode);
}

// Last node in sortedNodes is the root node
const root = sortedNodes.pop();

The complete sortScriptsIntoTree function looks like this:

export function sortScriptsIntoTree(inputs: Inputs): Taptree | undefined {
    const nodes: Node[] = inputs
        .map((value) => ({
            weight: value.weight,
            node: value.leaf
        }));

    const sortedNodes = new SortedList(
        nodes,
        (a, b) => a.weight - b.weight
    ); // Create a list sorted in ascending order of frequency

    let newNode: Node;
    let nodeA: Node, nodeB: Node;
    while (sortedNodes.length() > 1) {
        // Construct a new node from the two nodes with the least frequency
        nodeA = sortedNodes.pop()!; // There will always be an element to pop
        nodeB = sortedNodes.pop()!; // because loop ends when length <= 1
        newNode = {
            weight: nodeA.weight + nodeB.weight,
            node: [nodeA.node, nodeB.node]
        };
        // Place newNode back into sorted list
        sortedNodes.insert(newNode);
    }

    // Last node in sortedNodes is the root node
    const root = sortedNodes.pop();
    return root?.node;
}

Testing

The tests folder contains tests for the huffman constructor and the SortedList class. I check that the huffman constructor works when scripts are provided with equal weights, negative weights, infinity etc. I encourage you to take a look as this is the only way you can tell that the huffman constructor is doing what you expect it to do.

Conclusion

Thank you for reading, if you need help understanding how to spend taproot script paths, check out my article on creating taproot scripts.
You can find the github repo for this article, here

More on Taproot

Oghenovo Usiwoma — Sun, 26 Mar 2023 05:49:06 +0000

In a previous article, I gave a brief intro Taproot and shared some examples utilizing Taproot addresses.
In this article, I intend to share more information about taproot addresses and share one more example which I neglected in my previous article. I'll share:

Public Key Tweaking, what it is, why we do it and how we do it
How Taproot addresses are created
How to generate the private key required to sign a spending transaction from a Taproot address.
How to spend a Taproot output that has a script-tree without using any leaf scripts with bitcoinjs

Public Key Tweaking

What is Public key Tweaking

According to a workshop on taproot by Bitcoin Optech, you can tweak a public key by adding a value (the tweak) to it. This way, you can still spend the tweaked public key if you know the original private key and the tweak. It is used in taproot to commit data or scripts.

Why do we tweak keys

We tweak keys in taproot to commit to data or scripts that can be used for different spending conditions. This way, we can make complex transactions look like simple ones and save space and fees.

Why didn't we tweak before Taproot

Before taproot, we used a different type of digital signatures called ECDSA. ECDSA did not allow for easy tweaking. Taproot uses a new type of signatures called Schnorr that enable tweaking and other benefits.

How does a tweak work under the hood

A tweak is positive scalar value t where:

0 < t < SECP256K1_ORDER

In bitcoin cryptography, we use the elliptic curve secp256k1 and SECP256K1_ORDER is the number of points on the curve

A point, the Tweak point, is obtained from this tweak scalar value by multiplying it by the generator point:

T = t * G

The generator point is a special point that can produce any other point in its subgroup by multiplying it by some integer

This tweak point is added to the x-coordinate of the original public key to get the tweaked public key. Prepend a parity bit to this tweaked public key to indicate if it is positive or negative.

In taproot, we get the tweak value by concatenating the x-coordinate of the public key and a commitment to the script path to spend and hashing it. To spend a taproot output, you can sign with the tweaked private key (private key + tweak value) or provide a proof of the script path spend.

Creating a Taproot address

Taproot allows you to create addresses that can be spent by a single public key or by scripts. It does this by allowing you to add data to a public key by tweaking it.

To create a P2TR (Pay-to-Taproot) address for a single public key, you need to:

Check that the y-coordinate of your public key is even, if not, negate the public key. Taproot requires that the y coordinate of the public key is even.
extract the x-coordinate (bytes 1 to 33) of your public key (which is a point on an Elliptic Curve)
tweak the public key with this x-only part of the public key.
hash the x-coordinate of the tweaked public key with SHA256 and RIPEMD to get a 20-byte address.
Prepend the version byte 0x51(indicates that the taproot address is a native SegWit output with version 1) to the address to get a 21-byte witness program.
Encode the witness program with Bech32m encoding.

To create an address with multiple spending conditions (in the form of scripts), we arrange our scripts into a Merkle Tree, where each node is a hash of its children. The root of this tree is then used to tweak a public key and an address can be generated from this tweaked public key in the same steps (from step 4) defined above.

Even if you don't need multiple spending conditions for your address, BIP341 requires that you tweak the original public key with an unspendable script path which is what we do in step 3

Tweaking private keys for signing

To sign a transaction input spending a Taproot output, you need to tweak the private key for the original public key using the same tweak value that generated the address. If the public key was negated (see step 1 above) you must also negate the private key. The tweaked private key will create a valid Schnorr signature for the tweaked public key. This works because of the mathematical properties of Schnorr signatures and elliptic curves.

Spending a Taproot output with a script tree via the key path using bitcoinjs

In the Taptree example from my previous article. It is possible to spend the Taproot output without using the script tree.

// ...

const script_p2tr = payments.p2tr({
    internalPubkey: toXOnly(keypair.publicKey),
    scriptTree,
    network
});

// ...

const key_spend_psbt = new Psbt({ network });
key_spend_psbt.addInput({
    hash: utxos[0].txid,
    index: utxos[0].vout,
    witnessUtxo: { value: utxos[0].value, script: script_p2tr.output! },
    tapInternalKey: toXOnly(keypair.publicKey),
    tapMerkleRoot: script_p2tr.hash
});
key_spend_psbt.addOutput({
    address: "mohjSavDdQYHRYXcS3uS6ttaHP8amyvX78", // faucet address
    value: utxos[0].value - 150
});
// We need to create a signer tweaked by script tree's merkle root
const tweakedSigner = tweakSigner(keypair, { tweakHash: script_p2tr.hash });
key_spend_psbt.signInput(0, tweakedSigner);
key_spend_psbt.finalizeAllInputs();

tx = key_spend_psbt.extractTransaction();
console.log(`Broadcasting Transaction Hex: ${tx.toHex()}`);
txid = await broadcast(tx.toHex());
console.log(`Success! Txid is ${txid}`);

Thank you for reading!

HODL Invoices vs BOLT11 Invoices; A comparison

Oghenovo Usiwoma — Thu, 02 Mar 2023 07:16:17 +0000

Lightning is a second layer for Bitcoin that uses micropayment channels to scale the blockchain’s capability to conduct transactions more efficiently. This layer consists of multiple nodes that can open and close payment channels with each other, without having to broadcast every transaction to the Bitcoin network. This way, Lightning can enable faster and cheaper transactions, while still maintaining the security and decentralization of Bitcoin.

A Lightning invoice is a request for payment that contains the amount, destination, expiry time, and a cryptographic signature of the recipient. A payer can scan or copy a Lightning invoice and use it to initiate a payment through their Lightning wallet. A Lightning invoice can also include additional information such as a description or an image.

A Lightning HODL invoice is a special type of Lightning invoice that allows the recipient to delay the settlement of the payment until they reveal a preimage (a secret piece of data) that matches a hash (a unique fingerprint) embedded in the invoice. This feature can be useful for scenarios where the recipient wants to provide some service or proof before accepting the payment, such as delivering goods, verifying identity, or completing a task.

How to create a Bolt11 invoice with LND's API

See lnd's add-invoice API. You will need to specify:

The amount you want to receive in satoshis
The expiry time in milliseconds
The description (optional)
The preimage (optional, LND will generate one for you) Your invoice will be valid only for the expiry time you set. After it expires, it cannot be paid anymore. It can also be paid only once.

How to create a lightning HODL invoice with LND's API

See lnd's add-hodl-invoice API. A HODL invoice is very similar to a Bolt11 invoice but because the preimage is not released immediately on payment, you can cancel the invoice or settle it by releasing the preimage for the invoice.

Even if you don't release the preimage in a Bolt11 invoice, the invoice will not be canceled. The payer can keep trying to pay until the invoice expires or fails with incorrect_or_unknown_payment_details. LND also requires the preimage to generate a BOLT11 invoice, so you have no control over when it is revealed.

Conclusion

HODL invoices are good for situations where you want to receive payments only after fulfilling some condition or providing some service. For example,

You can use them for escrow services where you hold funds until both parties agree on releasing them
You can use them for atomic swaps where you exchange one cryptocurrency for another without trusting intermediaries
You can use them for pay-per-view content where you charge users only after they watch your video or read your article
You can use them for crowdfunding campaigns where you collect funds only after reaching your goal

HODL invoices are also good for enhancing privacy and security on the Lightning Network. By delaying payments until they are needed, you reduce the risk of losing funds due to channel closures, hacks, or thefts. You also reduce the amount of information that is exposed on the network, such as balances, fees, or routes.

HODL invoices are one of many innovations that make the Lightning Network more powerful and versatile. They demonstrate how Bitcoin’s native smart-contract scripting language can enable new possibilities for peer-to-peer transactions.

References

A Guide to creating TapRoot Scripts with bitcoinjs-lib

Oghenovo Usiwoma — Sun, 19 Feb 2023 21:31:40 +0000

Taproot and Schnorr are upgrades to the Bitcoin protocol designed to enhance the privacy, efficiency and flexibility of Bitcoin transactions.

Taproot introduces Taptrees, a feature that reduces the size of transaction data and ensures only necessary information is revealed on the blockchain, thereby preserving privacy. With Taproot, multisig transactions are also more private as unused spending conditions are hidden.

Schnorr signatures are 64 bytes long instead of the 72 bytes used by current ECDSA signature scheme. Taproot also use only x-values of public keys for signature creation which saves 1 byte.

With the adoption of Taproot and Schnorr, Bitcoin transactions can be more efficient, flexible, and private.

We'll go over two examples. In our first example, we will create a pay-to-taproot(p2tr) address that will lock funds to a key and create a spend transaction for it. In our second example, we will jump straight into taproot script-spend transactions, we will create a Taptree consisting of two script-spend paths, a hash-lock script spend path and a pay-to-pubkey script spend path. We will create transactions that spend from both paths.

The full code for this article can be found on github at taproot-with-bitcoinjs.

Taproot Key-spend transaction

For illustration purposes, we'll use a random keypair

const keypair = ECPair.makeRandom({ network });

We tweak this keypair with our pubkey.

const tweakedSigner = tweakSigner(keypair, { network });

bitcoinjs-lib provides a p2tr function to generate p2tr outputs.

const p2pktr = payments.p2tr({
  pubkey: toXOnly(tweakedSigner.publicKey),
  network
});
const p2pktr_addr = p2pktr.address ?? "";
console.log(p2pktr_addr);

The toXOnly function extracts the x-value of our public key.

You can use any testnet faucet that supports taproot addresses. I used testnet-faucet.com/btc-testnet while testing.

Creating a spend-transaction for this address with bitcoinjs-lib is straightforward.

const psbt = new Psbt({ network });
psbt.addInput({
        hash: utxos[0].txid,
        index: utxos[0].vout,
        witnessUtxo: { value: utxos[0].value, script: p2pktr.output! },
        tapInternalKey: toXOnly(keypair.publicKey)
});

psbt.addOutput({
        address: "mohjSavDdQYHRYXcS3uS6ttaHP8amyvX78", // faucet address
        value: utxos[0].value - 150
});

psbt.signInput(0, tweakedSigner);
psbt.finalizeAllInputs();

Extract the transaction and broadcast the transaction hex.

const tx = psbt.extractTransaction();
console.log(`Broadcasting Transaction Hex: ${tx.toHex()}`);
const txid = await broadcast(tx.toHex());
console.log(`Success! Txid is ${txid}`);

Taproot Script-spend transaction

We'll create a Tap tree with two spend paths, a hash-lock spend path and a pay-to-pubkey spend path.

The hash-lock script-spend path will require the spender to include a preimage that will produce the hash specified in the script.

Let's make another random keypair for our hash-lock script

const hash_lock_keypair = ECPair.makeRandom({ network });

Now, we will construct our hash-lock script

const secret_bytes = Buffer.from('SECRET');
const hash = crypto.hash160(secret_bytes);
// Construct script to pay to hash_lock_keypair if the correct preimage/secret is provided
const hash_script_asm = `OP_HASH160 ${hash.toString('hex')} OP_EQUALVERIFY ${toXOnly(hash_lock_keypair.publicKey).toString('hex')} OP_CHECKSIG`;
const hash_lock_script = script.fromASM(hash_script_asm);

Notice that script still requires a signature to unlock funds.

The pay-to-pubkey spend path is much simpler

const p2pk_script_asm = `${toXOnly(keypair.publicKey).toString('hex')} OP_CHECKSIG`;
const p2pk_script = script.fromASM(p2pk_script_asm);

We can now create our Taptree and p2tr address.

const scriptTree: Taptree = [
        {
            output: hash_lock_script
        },
        {
            output: p2pk_script
        }
];
const script_p2tr = payments.p2tr({
        internalPubkey: toXOnly(keypair.publicKey),
        scriptTree,
        network
});
const script_addr = script_p2tr.address ?? '';
console.log(script_addr);

You can deposit some test btc into the address using a testnet faucet like testnet-faucet.com/btc-testnet.

To spend on any of the leaf scripts, you must present the leafVersion, script and controlBlock for that leaf script. The control block is data required to prove that the leaf script exists in the script tree(merkle proof).

bitcoinjs-lib will generate the control block for us.

const hash_lock_redeem = {
    output: hash_lock_script,
    redeemVersion: 192,
};
const p2pk_redeem = {
    output: p2pk_script,
    redeemVersion: 192
}

const p2pk_p2tr = payments.p2tr({
    internalPubkey: toXOnly(keypair.publicKey),
    scriptTree,
    redeem: p2pk_redeem,
    network
});

const hash_lock_p2tr = payments.p2tr({
    internalPubkey: toXOnly(keypair.publicKey),
    scriptTree,
    redeem: hash_lock_redeem,
    network
});

console.log(`Waiting till UTXO is detected at this Address: ${script_addr}`);
let utxos = await waitUntilUTXO(script_addr)
console.log(`Trying the P2PK path with UTXO ${utxos[0].txid}:${utxos[0].vout}`);

const p2pk_psbt = new Psbt({ network });
p2pk_psbt.addInput({
    hash: utxos[0].txid,
    index: utxos[0].vout,
    witnessUtxo: { value: utxos[0].value, script: p2pk_p2tr.output! },
    tapLeafScript: [
        {
            leafVersion: p2pk_redeem.redeemVersion,
            script: p2pk_redeem.output,
            controlBlock: p2pk_p2tr.witness![p2pk_p2tr.witness!.length - 1] // extract control block from witness data
        }
    ]
});

p2pk_psbt.addOutput({
    address: "mohjSavDdQYHRYXcS3uS6ttaHP8amyvX78", // faucet address
    value: utxos[0].value - 150
});

p2pk_psbt.signInput(0, keypair);
p2pk_psbt.finalizeAllInputs();

let tx = p2pk_psbt.extractTransaction();
console.log(`Broadcasting Transaction Hex: ${tx.toHex()}`);
let txid = await broadcast(tx.toHex());
console.log(`Success! Txid is ${txid}`);

To spend using the hash-lock leaf script, we have to create a custom finalizer function. In our custom finalizer, we will create our witness stack of signature, preimage, original hash-lock script and our control block

const tapLeafScript = {
    leafVersion: hash_lock_redeem.redeemVersion,
    script: hash_lock_redeem.output,
    controlBlock: hash_lock_p2tr.witness![hash_lock_p2tr.witness!.length - 1]
};

const psbt = new Psbt({ network });
psbt.addInput({
    hash: utxos[0].txid,
    index: utxos[0].vout,
    witnessUtxo: { value: utxos[0].value, script: hash_lock_p2tr.output! },
    tapLeafScript: [
        tapLeafScript
    ]
});

psbt.addOutput({
    address: "mohjSavDdQYHRYXcS3uS6ttaHP8amyvX78", // faucet address
    value: utxos[0].value - 150
});

psbt.signInput(0, hash_lock_keypair);

// We have to construct our witness script in a custom finalizer

const customFinalizer = (_inputIndex: number, input: any) => {
    const scriptSolution = [
        input.tapScriptSig[0].signature,
        secret_bytes
    ];
    const witness = scriptSolution
        .concat(tapLeafScript.script)
        .concat(tapLeafScript.controlBlock);

    return {
        finalScriptWitness: witnessStackToScriptWitness(witness)
    }
}

psbt.finalizeInput(0, customFinalizer);

tx = psbt.extractTransaction();
console.log(`Broadcasting Transaction Hex: ${tx.toHex()}`);
txid = await broadcast(tx.toHex());
console.log(`Success! Txid is ${txid}`);

Conclusion

By reading this article, you should now have a better understanding of how to use bitcoinjs-lib to create and spend P2TR (Pay to Taproot) payments. With this knowledge, you are one step closer to leveraging the benefits of Taproot in your Bitcoin transactions, such as improved privacy, scalability, and the ability to create more complex smart contracts.
You can find more examples in bitcoinjs-lib's repo. The full code for this article can be found on github at taproot-with-bitcoinjs.
If you need some help understanding taproot, you can check this out More on Taproot.

Unlocking the Power of P2WSH: A Step-by-Step Guide to Creating and Spending Coins with Bitcoin Scripts using bitcoinjs-lib

Oghenovo Usiwoma — Mon, 13 Feb 2023 11:19:08 +0000

In the world of Bitcoin, addresses are used to specify how you want to receive coins. There are several types of addresses, each with its own properties and capabilities.

The simplest type is Pay-to-Pubkey-Hash (P2PKH), which is generated from a public key hash and is secure but lacks advanced features. The Pay-to-Witness-Public-Key-Hash (P2WPKH) address, introduced by the SegWit upgrade, is more efficient and has lower fees. Another type, Pay-to-Script-Hash (P2SH), supports complex scripts and the Pay-to-Witness-Script-Hash (P2WSH) address is a SegWit-upgraded version of P2SH. Both P2WPKH and P2WSH use the bech32 format, an efficient address format with a checksum to detect and correct errors. Bech32 addresses start with "bcrt" on the Regtest network, "tb" on the testnet network, and "bc" on the mainnet network.

The P2WSH (Pay-to-Witness-Script-Hash) format embeds a witness program that includes a hash of a script, instead of just a simple public key hash as in the case of P2PKH (Pay-to-Pubkey-Hash) addresses. The witness program acts as a placeholder for the actual script, which can be more complex and larger in size, but this complexity is hidden from the sender. When a transaction is made to a P2WSH address, the sender only needs to provide the witness program, and the actual script complexity is only processed when a transaction spending from the p2wsh address is validated by the network. This makes sending transactions to P2WSH addresses simple and easy for the sender, while the receiver bears the burden of handling the increased script complexity and transaction fees associated with more complex scripts.

In this article, we'll be focusing on the P2WSH address type and how to create and use them in transactions using the bitcoinjs-lib library. By the end of this article, you'll have a solid understanding of how to create, send, and spend coins locked with a witness script using P2WSH addresses.

This article assumes that you have a solid understanding of how bitcoin and bitcoin-scripting works

The complete code for this article can be found here

Creating a Pay-to-Witness-Script-Hash (P2WSH) address in bitcoin is a bit more complex than a standard Pay-to-Witness-Pubkey-Hash (P2WPKH) address, but it opens up a whole new world of possibilities for specifying complex scripts. In this article, we'll be using the bitcoinjs-lib library, which is a popular JavaScript library for working with Bitcoin transactions. We'll be using TypeScript for our code samples, but the same concepts apply to JavaScript as well.

We'll start by installing bitcoinjs-lib:

npm install bitcoinjs-lib

Next, we'll import the modules we need from the library:

import { networks, script, opcodes, payments, Psbt } from 'bitcoinjs-lib';

const network = networks.testnet;

Now, we'll start with a simple example. In this example, we'll use a very simple locking script. The locking script will POP 2 numbers from the stack and check that they sum up to 5:

OP_ADD 5 OP_EQUAL

We can create a P2WSH address for this script using bitcoinjs-lib.

const locking_script = script.compile([
  opcodes.OP_ADD,
  script.number.encode(5),
  opcodes.OP_EQUAL
])

Now we'll create our P2WSH address:

const p2wsh = payments.p2wsh({ redeem: { output: locking_script, network }, network });
console.log(p2wsh.address);

The P2WSH address will be logged to the console. Sending coins to this address will secure them with a hash of a script, instead of the script itself. The sender does not need to know the details of the script as the coins are locked with a simple scriptPubKey. The coins can only be unlocked by someone with the full redeemScript, which, when hashed, will match the hash value to which the coins are locked. You can now send coins to this address, which will be locked by the script. You can use a testnet faucet.

Let's create a transaction to spend from our Psbt.
We'll use the Psbt (Partially Signed Bitcoin Transaction) class from bitcoinjs-lib. The Psbt class allows us to create, update and finalize partially signed transactions.

We'll create a new instance of the Psbt class:

const psbt = new Psbt({ network });

Now, we'll add the input to the transaction. This is the P2WSH transaction that we want to spend:

psbt.addInput({
    hash: "<txid>",
    index: <vout>,
    witnessUtxo: {
        script: p2wsh.output!,
        value: <amount>
    },
    witnessScript: locking_script
});

Replace <txid>, <vout>, and <amount> with the corresponding values of the P2WSH transaction.

Next, we'll add an output to the transaction. This is where we'll send the coins to:

const toAddress = "<address>";
const toAmount = <amount>;
psbt.addOutput({
    address: toAddress,
    value: toAmount
});

Remember to leave a small amount to pay for transaction fees.

To spend from our address, we need to present any two numbers that add up to 5, so any of the following scripts will work:

We need to add our unlocking script to the input.

const finalizeInput = (_inputIndex: number, input: any) => {
  const redeemPayment = payments.p2wsh({
      redeem: {
        input: script.compile([
          script.number.encode(1),
          script.number.encode(4)
        ]),
        output: input.witnessScript
      }
    });

    const finalScriptWitness = witnessStackToScriptWitness(
      redeemPayment.witness ?? []
    );

    return {
      finalScriptSig: Buffer.from(""),
      finalScriptWitness
    }
}

psbt.finalizeInput(0, finalizeInput);

Notice that we don't need to sign the p2swh input because our locking script doesn't require a signature.

The witnessStackToScriptWitness takes our witness stack(which is an array of our locking script and witness script) and serializes it(coverts it into a single stream of bytes returned as a Buffer).

Now we can extract the transaction using:

const tx = psbt.extractTransaction();
console.log(tx.toHex());

And then broadcast it to the network using any method you prefer.

Let's create a slightly more complex script, where we can demonstrate how to add a signature to the unlocking script.
This time, we'll pay to an address(the script will be a standard p2pkh script) but we will require a secret to be presented along with the signature before the funds can be unlocked.

This is only an example, simple enough that I can use demonstrate adding signatures. In practice, I'm not sure why you would use a script like this without adding a conditional flow so that the coins can be spent in a different way if the secret is not provided

Take a look at our locking script:

OP_HASH160 <HASH160(<secret>)> OP_EQUALVERIFY OP_DUP OP_HASH160 <recipient_address> OP_EQUALVERIFY OP_CHECKSIG

Our unlocking script will take the form:

<signature> <pubkey> <secret>

We'll use the crypto module from 'bitcoinjs-lib' to hash our secret:

import { crypto } from 'bitcoinjs-lib';

const preimage = Buffer.from(secret);
const hash = crypto.hash160(preimage);

If you have a bech32 address, you will need to decode the address using the address module:

import { address } from 'bitcoinjs-lib';

const recipientAddr = address.fromBech32("<bech32 address>");

The address module can also decode standard p2pkh addresses or p2sh address encoded in base58check format.
Or you can make a random keypair and get the pubkey and address:

import { ECPairFactory, ECPairAPI, TinySecp256k1Interface } from 'ecpair';

const tinysecp: TinySecp256k1Interface = require('tiny-secp256k1');
const ECPair: ECPairAPI = ECPairFactory(tinysecp);

const keypair = ECPair.makeRandom({ network });
const publicKey = keypair.publicKey;
const recipAddr = crypto.hash160(publicKey);

Let's compile the locking script and create our p2wsh address:

const locking_script = script.compile([
  opcodes.OP_HASH160,
  hash,
  opcodes.OP_EQUALVERIFY,
  opcodes.OP_DUP,
  opcodes.OP_HASH160,
  recipAddr,
  opcodes.OP_EQUALVERIFY,
  opcodes.OP_CHECKSIG,
]);

const p2wsh = payments.p2wsh({ redeem: { output: locking_script, network }, network });
console.log(p2wsh.address);

You can send some coins to this address for testing.

To spend from this address, we'll perform the same steps we performed before but with a little twist; after adding the input and outputs, we'll need to create a signature for the p2wsh input:

psbt.signInput(0, keypair);

Next, we'll construct the unlocking script and add it to the input:

const finalizeInput = (_inputIndex: number, input: any) => {
    const redeemPayment = payments.p2wsh({
      redeem: {
        input: script.compile([
          input.partialSig[0].signature,
          publicKey,
          preimage
        ]),
        output: input.witnessScript
      }
    });

    const finalScriptWitness = witnessStackToScriptWitness(
      redeemPayment.witness ?? []
    );

    return {
      finalScriptSig: Buffer.from(""),
      finalScriptWitness
    }
}

psbt.finalizeInput(0, finalizeInput);

Now, we can extract the transaction hex and broadcast it:

const tx = psbt.extractTransaction();
console.log(tx.toHex());

And that's it! We've successfully created a P2WSH address, sent coins to it, and spent the coins locked with the witness script using bitcoinjs-lib. Keep in mind that this is just a simple example and there are many other ways to use P2WSH and scripts to lock and unlock coins in Bitcoin.

The complete code for this article can be found here

A good reason to create a Service Layer in your application

Oghenovo Usiwoma — Mon, 17 Oct 2022 09:44:29 +0000

Many developers are accustomed to the design pattern in which we break our application code into the models/entities layer, the repository layer, the service layer, and the controllers.

The reason for the entities layer is pretty straightforward: you must declare the fields(and their types) of entities in your application. In some applications, you can also describe the database schema in your entity class. You place your queries in the repository layer and use them to retrieve data, while your controllers contain handlers for each route and HTTP method. But what about Services?

I occasionally have service classes that appear to have no use other than to satisfy the need to have a service layer before my repositories.

I recently discovered a great reason to have service layer classes. A project I was working on had no clearly defined service layer. I needed to write code to pull data from different repos, process it and return the result. For the sake of this article, let's assume that I first wrote this code in the controller class.

const repo1 = new Repo1()
const repo2 = new Repo2()

@rest('/demo')
class DemoController {

  @get('/result')
  getResult(req) {
    // handler for GET /demo/result

    const stuff = repo1.findById(req.body.id)
    const moreStuff = repo2.findAllCreatedBefore(req.body.time)
    // do some processing here
    return { result } 
  }

}

Then I realized I needed it somewhere else, so I transferred it to a different file and wrapped the code in a function.

// process-data file
const repo1 = new Repo1()
const repo2 = new Repo2()

export function processData(id, time) {
  const stuff = repo1.findById(id)
  const moreStuff = repo2.findAllCreatedBefore(time)
  // do some processing here
  return result;
}

Now that I can use it everywhere, isn't my job done? No, not exactly. There is only one problem: How will I test this function?

The function has dependencies (the repositories) that are not part of its parameters which will make testing difficult. This function needs to use a set of mocked dependencies in my test cases. How do I go about doing this? Wouldn't a class be appropriate here?

// process-data file

export class DataProcessor {
  private repo1
  private repo2

  constructor(repo1, repo2) {
    this.repo1 = repo1
    this.repo2 = repo2
  }

  processDataByIdCreatedBeforeTime(id, time) {
    const stuff = this.repo1.findById(id)
    const moreStuff = this.repo2.findAllCreatedBefore(time)
    // do some processing here
    return result;
  }

}

export const processor = new DataProcessor(new Repo1(), new Repo2())

// test DataProcessor

it('should process the data correctly', () => {
  const processor = new DataProcessor(mock1, mock2)
  // ...some testing code
  const result = processor.processDataByIdCreatedBeforeTime(id, time)
  assert.equal(result, expectedResult)
})

In the example above, doesn't the DataProcessor class look like a Service layer class? The need to test the data processing logic eventually led to the creation of the service layer class. So, what should we take away?

You need the Service layer separate from your repositories and controllers so you can unit-test your business logic code
You also need the Service layer so that your business logic code can be reused in other parts of your application
Consider using Test Driven Development?

This is my opinion. I suspect that there may be contrary ideas or I may have missed something, in that case, feel free to share in the comments.
Thank you for reading.

A better way to create Swagger Docs for Koa APIs using decorators?

Oghenovo Usiwoma — Mon, 20 Jun 2022 10:35:06 +0000

Hello there!👋 I just did something to ease documentation for Koa APIs and I'm going to share it with you. If you are a fan of typescript's decorators or you are figuring out how to use them then you'll probably love this.

So, I had to setup swagger docs for a Koa API recently and I had to cram a lot of information and definitions into comments for the swagger-jsdoc tool to extract. As a developer who has used NestJS and is familiar with the ease at which you can create Swagger docs, I disliked this experience. I did check for some alternatives and found one notable package koa-swagger-decorator but why not re-invent the wheel 😃? I just wanted to code this myself... Thankfully, I got something usable without too much effort but this could easily have turned into a bad situation where I just wasted time and effort instead of using an existing solution.

Alright, let's get started!
So, I wanted something similar to what NestJS offers; I wanted to create classes to represent my various definitions and I wanted to use decorators to add swagger specific information to it's properties, Piece of cake...

This is an example of what I had in mind for Definitions...

@Definition()
export class CreateUser {
    @ApiProperty({
        required: true,
        type: 'string'
    })
    createdBy!: string

    @ApiProperty({
        required: true,
        type: 'string'
    })
    username!: string

    @ApiProperty({
        required: true,
        type: 'string'
    })
    city!: string
}

We will have to do some work at the Controller level too but let's start here.
Creating the decorators is easy enough, you only need peruse the Typescript documentation but I mostly skipped that step and that came back to haunt me later but let's proceed.

How Decorators work

A decorator is a function that can be attached to classes, methods, properties etc, and get's called at runtime with details about the declaration it is attached to(let's call this the decorated entity). You can also modify said decorated entity at runtime. A couple of things to note about decorators;

When you have multiple decorators in a class, the parameter decorators, the method/property decorators, and the class decorators are evaluated serially in that order
When you have multiple decorators attached to the same entity, they are evaluated top-to-bottom and the results are passed bottom-to-top

A bit oversimplified but checkout Decorator composition for more information.

Creating the "ApiProperty" and "Definition" decorators

We need to store information like required fields, property types, examples if any for each Definition. I decided that a single "@ApiProperty" will suffice for this and "@Definition" will be added to the class to compile all the collected information into one definition and added to our definitions list... See the code snippet below.

export const DEFINITIONS: any = {}; // to hold all definitions
let DEFINITION: any = {}; // current definition details

// class decorator
export function Definition() {
    return function <T extends { new(...args: any[]): {} }>(constructor: T) {
        DEFINITIONS[constructor] = {
            name: constructor.name,
            type: "object",
            ...DEFINITION
        };
        DEFINITION = {}; // prepare for next class
    }
}

Why am I using the class constructor as key for the Definition object? well, we will see that in the next section...

export interface ApiPropertyProps {
    required?: boolean
    type: string
    example?: string
    items?: { $ref?: any }
}

// A function that returns the actual decorator, A decorator factory
export function ApiProperty(props: ApiPropertyProps) {
    return function (_target: any, propertyKey: string) {
        if (!DEFINITION.required) DEFINITION.required = [];
        if (!DEFINITION.properties) DEFINITION.properties = {};

        if (props.required) DEFINITION.required.push(propertyKey);
        if (props.items?.$ref) props.items.$ref = toSwaggerRef(props.items.$ref); // convert ref to swagger ref format

        DEFINITION.properties = { ...DEFINITION.properties, [propertyKey]: props };
    }
}

The Controllers

Now, we can't just define routes using koa-router because we can only use decorators in classes. So, we need to make Controller classes and also create decorators to add path, parameters and response definitions. I ended with something this..

class UserController {
    @ApiParameter({ in: 'body', schema: { $ref: CreateUser } })
    @ApiResponse({ status: 200, type: 'application/json', schema: { $ref: CreateUser } })
    @ApiOperation({ path: '/user/create', method: 'post' })
    async createUser(ctx: Context) {
        const body: CreateGroup = ctx.request.body;
        console.log(body);
    }
}

If you are worried about adding middleware, it's easy enough to create a "Middleware" decorator for this purpose.

Notice here, that $ref points to the actual CreateUser class. I did this to ensure that the decorators applied to CreateUser actually get executed at runtime. Without this limitation, I'd have to find other ways to make sure CreateUser actually gets added to the Definitions

The toSwaggerRef function as is shown below will be responsible for converting these class references to "#/definitions/CreateUser" strings for swagger to interpret.

function toSwaggerRef(ref: any) {
    if (ref.charAt) return ref; // quick check if ref is a string
    const definition = DEFINITIONS[ref];
    return `#/definitions/${definition.name}`;
}

The code for the "ApiParameter" and "ApiResponse" decorators are pretty standard and you can take a look at them in the github gist. For "@ApiOperation", I modified the decorated method's instance a little bit to make it easier to add the routes to koa using koa-router.

export interface ApiOperationProps {
    path: string, // Api Path
    method: Methods, // Http Methods
    description?: string
    consumes?: string[]
}

export function ApiOperation(props: ApiOperationProps) {
    const swaggerPath = props.path.split('/')
        .map(token => {
            if (!token.startsWith(':')) return token;
            return `{${token.slice(1)}}`;
        })
        .join('/'); // convert all ':param' to '{param}' for swagger

    PATHS[swaggerPath] = {
        [props.method]: {
            description: props.description,
            consumes: props.consumes,
            parameters: PARAMETERS,
            responses: RESPONSES
        }
    }
    PARAMETERS = [];
    RESPONSES = {};

    return (target: any, propertyKey: string, _descriptor: PropertyDescriptor) => {
        // target is the instance with decorated property
        if (!target._paths) target._paths = [];
        target._paths.push({
            path: props.path,
            method: props.method, // method as in Http Method
            propertyKey
        });
    }
}

Putting it all together

So, let's add our routes to koa and then generate our swagger doc...

export function applyRoutes(controller: any, router: Router) {
    if (!controller._paths) return;

    // Remember the paths we added in the @ApiOperation decorator?
    controller._paths.forEach((pathObj: any) => {
        const { path, method, propertyKey } = pathObj;
        router[method as Methods](path, controller[propertyKey]); // Register route
    });
}

In our controller file, after defining our controller class, we just need to do this...

const router = new Router();
const users = new UserController();
applyRoutes(users, router);

export default router; // add this to the koa app

To get our swagger page, I used this tool, swagger2-koa which accepts any object following the swagger specification...

The swaggerDoc function compiles the paths and definitions into one object following the swagger specification.

export interface SwaggerProps {
    info: {
        title: string,
        version: string,
        description: string
    }
}

export function swaggerDoc(props: SwaggerProps) {
    const definitions = getDefinitions(); // Parse our DEFINITIONS object into the swagger format

    return {
        swagger: "2.0",
        info: props.info,
        paths: PATHS,
        definitions,
        responses: {},
        parameters: {},
        securityDefinitions: {},
        tags: {}
    };
}

and finally...

import { ui } from 'swagger2-koa';
import { swaggerDoc } from './utils/swagger';

let swaggerSpec: any = swaggerDoc({
    info: {
        title: `Test API`,
        version: '1.0.0',
        description: `Test API`
    }
});

const swagger = ui(swaggerSpec, "/swagger");

// add to koa app
app.use(swagger);

Conclusion

This was mostly fun... I like to do things like this from time-to-time to prove that I'm still an "okay" programmer 💀. The full code is available here.

Thank you for reading!

DEV Community: Oghenovo Usiwoma

Elliptic Curve Concepts for Bitcoin Developers

Definition of Elliptic Curves

Finite Fields

Why can't we define the curve over Real Numbers?

Order of a Finite Field

Modular Arithmetic

Simple n-modulo Finite Fields

The Elliptic Curve Group

Inverting an Elliptic Curve Point

Addition of Elliptic Curve Points

Scalar Multiplication

Elliptic Curve Subgroups

Elliptic Curve Parameters

Order of the field, p

Generator Point, G

Order of the subgroup, n

The Coefficients of the curve, a, b

The cofactor, h

Projected Coordinates

The secp256k1 Curve

Discrete Logarithm Problem

Secret and Public Keys

Conclusion

What I missed about BIP143's scriptCode

Conclusion

The PSBT Standard

The PSBT Binary format

Signing a PSBT

Finalizing a PSBT

Extracting a serialized transaction

Conclusion

NodeJS Stream Processing: Build a Simple multipart/form-data parser

The multipart/form-data format

The plan

Split data processing into multiple stages

The Implementation

Conclusion

Introduction to Miniscript

Policies and Fragments

The Miniscript Type System

Conclusion

Minimalizing Witness weight for Taproot spend script paths with Huffman's Algorithm

TLDR

Introduction

The Method

Implementation

Step 1

Step 2

Step 3

Step 4

Testing

Conclusion

More on Taproot

Public Key Tweaking

What is Public key Tweaking

Why do we tweak keys

Why didn't we tweak before Taproot

How does a tweak work under the hood

Creating a Taproot address

Tweaking private keys for signing

Spending a Taproot output with a script tree via the key path using bitcoinjs

HODL Invoices vs BOLT11 Invoices; A comparison

How to create a Bolt11 invoice with LND's API

How to create a lightning HODL invoice with LND's API

Conclusion

References

A Guide to creating TapRoot Scripts with bitcoinjs-lib

Taproot Key-spend transaction

Taproot Script-spend transaction

Conclusion

Unlocking the Power of P2WSH: A Step-by-Step Guide to Creating and Spending Coins with Bitcoin Scripts using bitcoinjs-lib

A good reason to create a Service Layer in your application

A better way to create Swagger Docs for Koa APIs using decorators?

How Decorators work

Creating the "ApiProperty" and "Definition" decorators

The Controllers

Putting it all together

Conclusion

Order of the field, `p`

Generator Point, `G`

Order of the subgroup, `n`

The Coefficients of the curve, `a`, `b`