lighstorm 0.0.6 → 0.0.8

data/docs/README.md

@@ -6,9 +6,13 @@
 
 _Lighstorm_ is an opinionated abstraction layer on top of the [lnd-client](https://github.com/icebaker/lnd-client).
 
-It brings an [object-oriented](https://en.wikipedia.org/wiki/Object-oriented_programming) approach for interacting with a [Lightning Node](https://github.com/lightningnetwork/lnd), influenced by the [Active Record Pattern](https://www.martinfowler.com/eaaCatalog/activeRecord.html) and [Active Record Models](https://guides.rubyonrails.org/active_record_basics.html) conventions.
+It brings an [_object-oriented_](https://en.wikipedia.org/wiki/Object-oriented_programming) approach for interacting with a [Lightning Node](https://github.com/lightningnetwork/lnd), influenced by the [Active Record Pattern](https://www.martinfowler.com/eaaCatalog/activeRecord.html) and [Active Record Models](https://guides.rubyonrails.org/active_record_basics.html) conventions.
 
-Although it tries to stay close to [Lightning's terminologies](https://docs.lightning.engineering/lightning-network-tools/lnd), it brings its own vocabulary and [data modeling](#data-modeling), optimizing for [programmer happiness](https://rubyonrails.org/doctrine).
+However, despite the fluidity of _Object Orientation_ being desired in its public interface, internally, most of its code is structured following the [_Hexagonal Architecture_](https://en.wikipedia.org/wiki/Hexagonal_architecture_(software)) and [_Functional Programming_](https://en.wikipedia.org/wiki/Functional_programming) principles.
+
+It aims to be intuitive to use while being highly **reliable**, as it deals with people's money, and easily testable since its [tests](?id=testing) are the foundation for its reliability.
+
+Although it tries to stay close to [Lightning's terminologies](https://docs.lightning.engineering/the-lightning-network/overview), it brings its own vocabulary and [data modeling](?id=data-modeling), optimizing for [programmer happiness](https://rubyonrails.org/doctrine#optimize-for-programmer-happiness).
 
 # Getting Started
 
@@ -23,7 +27,7 @@ Lighstorm::Channel.mine.first.myself.node.alias
 Add to your `Gemfile`:
 
 ```ruby
-gem 'lighstorm', '~> 0.0.6'
+gem 'lighstorm', '~> 0.0.8'
 ```
 
 Run `bundle install`.
@@ -56,11 +60,11 @@ Lighstorm.config!(
 ```ruby
 require 'lighstorm'
 
-puts Lighstorm.version # => 0.0.6
+puts Lighstorm.version # => 0.0.8
 
-Lighstorm::Satoshis.new(
-  milisatoshis: 75_621_650
-).satoshis # => 75_621
+Lighstorm::Invoice.create(
+  description: 'Coffee', millisatoshis: 1000
+)
 
 Lighstorm::Node.myself.alias # => icebaker/old-stone
 Lighstorm::Node.myself.public_key # => 02d3...e997
@@ -73,7 +77,7 @@ Lighstorm::Channel.mine.first.partner.node.alias
 
 forward = Lighstorm::Forward.all(limit: 10).first
 
-forward.in.amount.milisatoshis # => 75621650
+forward.in.amount.millisatoshis # => 75621650
 forward.in.amount.satoshis # => 75621
 forward.in.amount.bitcoins # => 0.0007562165
 forward.in.channel.partner.node.alias
@@ -88,6 +92,10 @@ payment.to.channel.id # => 821539695188246532
 payment.amount.sats # => 957262
 payment.hops.size # => 4
 payment.hops.first.channel.partner.node.alias
+
+Lighstorm::Satoshis.new(
+  millisatoshis: 75621650
+).satoshis # => 75621
 ```
 
 # Data Modeling
@@ -105,20 +113,20 @@ So, we are going to think in terms of _Edges_, _Nodes_, and _Connections_:
   </a>
 </center>
 
-## Channel
+### Channel
 
 ```ruby
 channel = Lighstorm::Channel.mine.first
 
 channel.id
 
-channel.accounting.capacity.milisatoshis
+channel.accounting.capacity.millisatoshis
 
-channel.partner.accounting.balance.milisatoshis
+channel.partner.accounting.balance.millisatoshis
 channel.partner.node.alias
 channel.partner.policy.fee.rate.parts_per_million
 
-channel.myself.accounting.balance.milisatoshis
+channel.myself.accounting.balance.millisatoshis
 channel.myself.node.alias
 channel.myself.policy.fee.rate.parts_per_million
 ```
@@ -130,18 +138,18 @@ channel.myself.policy.fee.rate.parts_per_million
   </a>
 </center>
 
-## Forward
+### Forward
 
 ```ruby
 forward = Lighstorm::Forward.last
 
 forward.at
 
-forward.fee.milisatoshis
+forward.fee.millisatoshis
 forward.fee.parts_per_million
 
-forward.in.amount.milisatoshis
-forward.out.amount.milisatoshis
+forward.in.amount.millisatoshis
+forward.out.amount.millisatoshis
 
 forward.in.channel.id
 forward.in.channel.partner.node.alias
@@ -157,7 +165,7 @@ forward.out.channel.partner.node.alias
   </a>
 </center>
 
-## Payment
+### Payment
 
 ```ruby
 payment = Payment.last
@@ -168,24 +176,24 @@ payment.created_at
 # https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
 payment.request.code # "lnbc20m1pv...qqdhhwkj"
 
-payment.request.amount.milisatoshis
+payment.request.amount.millisatoshis
 
 payment.from.hop
-payment.from.amount.milisatoshis
-payment.from.fee.milisatoshis
+payment.from.amount.millisatoshis
+payment.from.fee.millisatoshis
 payment.from.channel.id
 payment.from.channel.target.alias
 payment.from.channel.exit.alias
 
 payment.to.hop
-payment.to.amount.milisatoshis
-payment.to.fee.milisatoshis
+payment.to.amount.millisatoshis
+payment.to.fee.millisatoshis
 payment.to.channel.id
 payment.to.channel.target.alias
 
 payment.hops[0].hop
-payment.hops[0].amount.milisatoshis
-payment.hops[0].fee.milisatoshis
+payment.hops[0].amount.millisatoshis
+payment.hops[0].fee.millisatoshis
 payment.hops[0].channel.id
 payment.hops[0].channel.target.alias
 ```
@@ -197,80 +205,6 @@ payment.hops[0].channel.target.alias
   </a>
 </center>
 
-# Error Handling
-
-## Rescuing
-```ruby
-require 'lighstorm'
-
-channel = Lighstorm::Channel.mine.first
-
-begin
-  channel.myself.policy.fee.update(
-    { rate: { parts_per_million: -1 } }, preview: true
-  )
-rescue Lighstorm::Errors::NegativeNotAllowedError => error
-  puts error.message # 'fee rate can't be negative: -1'
-end
-
-begin
-  channel.myself.policy.fee.update(
-    { rate: { parts_per_million: -1 } }, preview: true
-  )
-rescue Lighstorm::Errors::LighstormError => error
-  puts error.message # 'fee rate can't be negative: -1'
-end
-```
-
-### For Short
-
-```ruby
-require 'lighstorm'
-require 'lighstorm/errors'
-
-channel = Lighstorm::Channel.mine.first
-
-begin
-  channel.myself.policy.fee.update(
-    { rate: { parts_per_million: -1 } }, preview: true
-  )
-rescue NegativeNotAllowedError => error
-  puts error.message # "fee rate can't be negative: -1"
-end
-
-begin
-  channel.myself.policy.fee.update(
-    { rate: { parts_per_million: -1 } }, preview: true
-  )
-rescue LighstormError => error
-  puts error.message # "fee rate can't be negative: -1"
-end
-```
-
-## Errors
-```ruby
-LighstormError
-
-IncoherentGossipError
-
-TooManyArgumentsError
-MissingCredentialsError
-MissingGossipHandlerError
-MissingMilisatoshisError
-MissingPartsPerMillionError
-MissingTTLError
-
-NegativeNotAllowedError
-
-NotYourChannelError
-NotYourNodeError
-UnknownChannelError
-
-OperationNotAllowedError
-UnexpectedNumberOfHTLCsError
-UpdateChannelPolicyError
-```
-
 # API
 
 ## Node
@@ -338,10 +272,10 @@ channel.state
 channel.active?
 channel.exposure
 
-channel.accounting.capacity.milisatoshis
-channel.accounting.sent.milisatoshis
-channel.accounting.received.milisatoshis
-channel.accounting.unsettled.milisatoshis
+channel.accounting.capacity.millisatoshis
+channel.accounting.sent.millisatoshis
+channel.accounting.received.millisatoshis
+channel.accounting.unsettled.millisatoshis
 
 # Channels that don't belong to you:
 channel.partners
@@ -364,13 +298,13 @@ channel.partner.node.public_key
 channel.partner.node.alias
 channel.partner.node.color
 
-channel.partner.accounting.balance.milisatoshis
+channel.partner.accounting.balance.millisatoshis
 
-channel.partner.policy.fee.base.milisatoshis
+channel.partner.policy.fee.base.millisatoshis
 channel.partner.policy.fee.rate.parts_per_million
 
-channel.partner.policy.htlc.minimum.milisatoshis
-channel.partner.policy.htlc.maximum.milisatoshis
+channel.partner.policy.htlc.minimum.millisatoshis
+channel.partner.policy.htlc.maximum.millisatoshis
 channel.partner.policy.htlc.blocks.delta.minimum
 
 channel.myself
@@ -381,17 +315,17 @@ channel.myself.node.public_key
 channel.myself.node.alias
 channel.myself.node.color
 
-channel.myself.accounting.balance.milisatoshis
+channel.myself.accounting.balance.millisatoshis
 
-channel.myself.policy.fee.base.milisatoshis
+channel.myself.policy.fee.base.millisatoshis
 channel.myself.policy.fee.rate.parts_per_million
 
-channel.myself.policy.htlc.minimum.milisatoshis
-channel.myself.policy.htlc.maximum.milisatoshis
+channel.myself.policy.htlc.minimum.millisatoshis
+channel.myself.policy.htlc.maximum.millisatoshis
 channel.myself.policy.htlc.blocks.delta.minimum
 ```
 
-### Operations
+### Fee Update
 
 ```ruby
 channel = Lighstorm::Channel.mine.first
@@ -403,7 +337,7 @@ channel.myself.policy.fee.update(
 )
 
 channel.myself.policy.fee.update(
-  { base: { milisatoshis: 1 } }
+  { base: { millisatoshis: 1 } }
 )
 
 channel.myself.policy.fee.update(
@@ -411,7 +345,7 @@ channel.myself.policy.fee.update(
 )
 
 channel.myself.policy.fee.update(
-  { base: { milisatoshis: 1 }, rate: { parts_per_million: 25 } }
+  { base: { millisatoshis: 1 }, rate: { parts_per_million: 25 } }
 )
 ```
 
@@ -426,6 +360,8 @@ Lighstorm::Invoice.all(limit: 10)
 Lighstorm::Invoice.first
 Lighstorm::Invoice.last
 
+Lighstorm::Invoice.decode('lnbc20n1pj...0eqps7h0k9')
+
 Lighstorm::Invoice.find_by_secret_hash(
   '1d438b8100518c9fba0a607e3317d6b36f74ceef3a6591836eb2f679c6853501'
 )
@@ -444,7 +380,7 @@ invoice.state
 # https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
 invoice.request.code # "lnbc20m1pv...qqdhhwkj"
 
-invoice.request.amount.milisatoshis
+invoice.request.amount.millisatoshis
 
 invoice.request.description.memo
 invoice.request.description.hash
@@ -456,20 +392,25 @@ invoice.request.secret.hash
 invoice.request.address
 ```
 
-### Operations
+### Create
 
 [Understanding Lightning Invoices](https://docs.lightning.engineering/the-lightning-network/payment-lifecycle/understanding-lightning-invoices)
 
 ```ruby
 # 'preview' let you check the expected operation
 # before actually performing it for debug purposes
-invoice = Lighstorm::Invoice.create(
-  milisatoshis: 1000, description: 'Coffee', preview: true
+preview = Lighstorm::Invoice.create(
+  description: 'Coffee', millisatoshis: 1000, preview: true
 )
 
-invoice = Lighstorm::Invoice.create(
-  milisatoshis: 1000, description: 'Piña Colada'
+action = Lighstorm::Invoice.create(
+  description: 'Piña Colada', millisatoshis: 1000
 )
+
+action.to_h
+
+action.response
+invoice = action.result
 ```
 
 ## Payment
@@ -504,15 +445,15 @@ payment.created_at
 payment.settled_at
 payment.purpose
 
-payment.fee.milisatoshis
+payment.fee.millisatoshis
 payment.fee.parts_per_million(
-  payment.request.amount.milisatoshis
+  payment.request.amount.millisatoshis
 )
 
 # https://github.com/lightning/bolts/blob/master/11-payment-encoding.md
 payment.request.code # "lnbc20m1pv...qqdhhwkj"
 
-payment.request.amount.milisatoshis
+payment.request.amount.millisatoshis
 
 # https://docs.lightning.engineering/the-lightning-network/multihop-payments
 payment.request.secret.preimage
@@ -524,9 +465,9 @@ payment.request.description.memo
 payment.request.description.hash
 
 payment.from.hop
-payment.from.amount.milisatoshis
-payment.from.fee.milisatoshis
-payment.from.fee.parts_per_million(payment.from.amount.milisatoshis)
+payment.from.amount.millisatoshis
+payment.from.fee.millisatoshis
+payment.from.fee.parts_per_million(payment.from.amount.millisatoshis)
 
 payment.from.channel.id
 
@@ -539,9 +480,9 @@ payment.from.channel.exit.alias
 payment.from.channel.exit.color
 
 payment.to.hop
-payment.to.amount.milisatoshis
-payment.to.fee.milisatoshis
-payment.to.fee.parts_per_million(payment.to.amount.milisatoshis)
+payment.to.amount.millisatoshis
+payment.to.fee.millisatoshis
+payment.to.fee.parts_per_million(payment.to.amount.millisatoshis)
 
 payment.to.channel.id
 
@@ -559,9 +500,9 @@ payment.hops[0].first?
 payment.hops[0].last?
 
 payment.hops[0].hop
-payment.hops[0].amount.milisatoshis
-payment.hops[0].fee.milisatoshis
-payment.hops[0].fee.parts_per_million(payment.hops[0].amount.milisatoshis)
+payment.hops[0].amount.millisatoshis
+payment.hops[0].fee.millisatoshis
+payment.hops[0].fee.parts_per_million(payment.hops[0].amount.millisatoshis)
 
 payment.hops[0].channel.id
 
@@ -611,19 +552,19 @@ forward._key
 
 forward.at
 
-forward.fee.milisatoshis
+forward.fee.millisatoshis
 forward.fee.parts_per_million(
-  forward.in.amount.milisatoshis
+  forward.in.amount.millisatoshis
 )
 
-forward.in.amount.milisatoshis
+forward.in.amount.millisatoshis
 
 forward.in.channel.id
 forward.in.channel.partner.node.alias
 forward.in.channel.partner.node.public_key
 forward.in.channel.partner.node.color
 
-forward.out.amount.milisatoshis
+forward.out.amount.millisatoshis
 
 forward.out.channel.id
 forward.out.channel.partner.node.alias
@@ -646,12 +587,12 @@ group._key
 
 group.last_at
 group.analysis.count
-group.analysis.sums.amount.milisatoshis
-group.analysis.sums.fee.milisatoshis
-group.analysis.averages.amount.milisatoshis
-group.analysis.averages.fee.milisatoshis
+group.analysis.sums.amount.millisatoshis
+group.analysis.sums.fee.millisatoshis
+group.analysis.averages.amount.millisatoshis
+group.analysis.averages.fee.millisatoshis
 group.analysis.averages.fee.parts_per_million(
-  group.analysis.averages.amount.milisatoshis
+  group.analysis.averages.amount.millisatoshis
 )
 
 group.channel.id
@@ -725,11 +666,11 @@ Lighstorm::Channel.adapt(dump: channel.dump)
 
 ```ruby
 Lighstorm::Satoshis
-Lighstorm::Satoshis.new(milisatoshis: 75_621_650)
+Lighstorm::Satoshis.new(millisatoshis: 75621650)
 
 satoshis.to_h
 
-satoshis.milisatoshis
+satoshis.millisatoshis
 satoshis.satoshis
 satoshis.bitcoins
 
@@ -737,13 +678,319 @@ satoshis.msats
 satoshis.sats
 satoshis.btc
 
-reference_in_milisatoshis = 75_621_650_000
-satoshis.parts_per_million(reference_in_milisatoshis)
+reference_in_millisatoshis = 75621650000
+satoshis.parts_per_million(reference_in_millisatoshis)
+```
+
+# Error Handling
+
+## Rescuing
+```ruby
+require 'lighstorm'
+
+channel = Lighstorm::Channel.mine.first
+
+begin
+  channel.myself.policy.fee.update(
+    { rate: { parts_per_million: -1 } }, preview: true
+  )
+rescue Lighstorm::Errors::NegativeNotAllowedError => error
+  puts error.message # 'fee rate can't be negative: -1'
+end
+
+begin
+  channel.myself.policy.fee.update(
+    { rate: { parts_per_million: -1 } }, preview: true
+  )
+rescue Lighstorm::Errors::LighstormError => error
+  puts error.message # 'fee rate can't be negative: -1'
+end
+```
+
+### For Short
+
+```ruby
+require 'lighstorm'
+require 'lighstorm/errors'
+
+channel = Lighstorm::Channel.mine.first
+
+begin
+  channel.myself.policy.fee.update(
+    { rate: { parts_per_million: -1 } }, preview: true
+  )
+rescue NegativeNotAllowedError => error
+  puts error.message # "fee rate can't be negative: -1"
+end
+
+begin
+  channel.myself.policy.fee.update(
+    { rate: { parts_per_million: -1 } }, preview: true
+  )
+rescue LighstormError => error
+  puts error.message # "fee rate can't be negative: -1"
+end
 ```
+
+## Errors
+```ruby
+LighstormError
+
+IncoherentGossipError
+
+TooManyArgumentsError
+MissingCredentialsError
+MissingGossipHandlerError
+MissingMillisatoshisError
+MissingPartsPerMillionError
+MissingTTLError
+
+NegativeNotAllowedError
+
+NotYourChannelError
+NotYourNodeError
+UnknownChannelError
+
+OperationNotAllowedError
+UnexpectedNumberOfHTLCsError
+UpdateChannelPolicyError
+```
+
+# Development
+
+Copy the `.env.example` file to `.env` and provide the required data.
+
+```ruby
+# Gemfile
+gem 'lighstorm', path: '/home/user/lighstorm'
+
+# demo.rb
+require 'lighstorm'
+
+puts Lighstorm.version # => 0.0.8
+```
+
+```sh
+bundle
+rubocop -A
+```
+
+## Testing
+
+Copy the `.env.example` file to `.env` and provide the required data.
+
+```
+bundle
+
+bundle exec rspec
+```
+### Approach
+
+Writing tests for software that indirectly performs [blockchain](https://en.wikipedia.org/wiki/Blockchain) operations, relies on an external [gRPC](https://grpc.io) API, and is highly influenced by volatile and uncertain [states](https://en.wikipedia.org/wiki/State_(computer_science)) can be [challenging](https://www.youtube.com/watch?v=lKXe3HUG2l4).
+
+While aiming for the _look and feel_ of _[Object Orientation](https://en.wikipedia.org/wiki/Object-oriented_programming)_, I don't want a mesh of objects with volatile states that can change at any time. I'm not saying it wouldn't be possible to make it reliable and easily testable this way, but I choose to follow a [_Functional Programming_](https://en.wikipedia.org/wiki/Functional_programming) approach internally, as my knowledge and experience can provide greater reliability for the software this way.
+
+The core idea is to separate **data** from **behavior** as much as possible. So, a _Model_ internally is just a dummy wrapper that _models_ the data to provide a fluid experience. Alongside that, I make things as [small as possible](https://www.youtube.com/watch?v=8bZh5LMaSmE) and extract desired results from composing them.
+
+Let's get practical.
+
+#### Requesting
+
+To _request_ all Nodes you:
+```ruby
+Lighstorm::Node.all
+```
+
+Internally, what's happening:
+```ruby
+nodes = Lighstorm::Node.all
+
+         data = Controllers::Node::All.fetch # side effect
+      adapted = Controllers::Node::All.adapt(data) # pure
+  transformed = Controllers::Node::All.transform(adapted) # pure
+       models = Controllers::Node::All.model(transformed) # pure
+        nodes = models # pure
+
+nodes.first.public_key
+```
+
+So, `fetch` -> `adapt` -> `transform` -> `model`:
+
+![A diagram illustrating the Request Process described above.](https://raw.githubusercontent.com/icebaker/assets/main/lighstorm/request.png)
+
+The advantage of this approach is that only `fetch` may generate [side effects](https://en.wikipedia.org/wiki/Side_effect_(computer_science)). All other methods ( `adapt`, `transform`,  `model`) are [pure functions](https://en.wikipedia.org/wiki/Pure_function). This means that most of the code is easily testable and reliable, and `fetch` is the only thing we need [mock](https://en.wikipedia.org/wiki/Mock_object) in tests and worry about possible side effects.
+
+The downside is that we can't [lazy-load](https://en.wikipedia.org/wiki/Lazy_loading) data, as we must know what data we will need beforehand.
+
+#### Performing Actions
+
+To perform an _action_, like creating an Invoice, you:
+```ruby
+Lighstorm::Invoice.create(
+  description: 'Coffee', millisatoshis: 1000
+)
+```
+
+Internally, what's happening:
+```ruby
+action = Lighstorm::Invoice.create(description: 'Coffee', millisatoshis: 1000)
+
+   request = Controllers::Invoice::Create.prepare(params) # pure
+  response = Controllers::Invoice::Create.dispatch(request) # side effect
+   adapted = Controllers::Invoice::Create.adapt(response) # pure
+      data = Controllers::Invoice::Create.fetch(adapted) # side effect
+     model = Controllers::Invoice::Create.model(data) # pure
+    action = { response: response, result: model } # pure
+
+invoice = action.result
+```
+
+So, `prepare` -> `dispatch` -> `adapt` -> `fetch` -> `model`:
+
+![A diagram illustrating the Action Process described above.](https://raw.githubusercontent.com/icebaker/assets/main/lighstorm/action.png)
+
+The advantage of this approach is that only `dispatch` and `fetch` may generate [side effects](https://en.wikipedia.org/wiki/Side_effect_(computer_science)). All other methods ( `prepare`, `adapt`,  `model`) are [pure functions](https://en.wikipedia.org/wiki/Pure_function). This means that most of the code is easily testable and reliable. `dispatch` and `fetch` are the only things we need [mock](https://en.wikipedia.org/wiki/Mock_object) in tests and worry about possible side effects.
+
+### VCR
+
+After understanding the [approach](?id=approach), we need to make [mocking](https://en.wikipedia.org/wiki/Mock_object) as straightforward as possible for a painless test writing experience, which leads to lots of tests being written, improving the reliability of the code.
+
+_Mock_ is not precisely the approach we are going to use. Instead, we're going to make side effects easily reproducible. The internal [VCR](https://github.com/icebaker/lighstorm/blob/main/spec/helpers/vcr.rb) helper - _whose name is influenced by the [vcr](https://github.com/vcr/vcr) project but has an entirely different implementation_ - provides two kinds of reproducible recordings:
+
+**Tape:**
+
+It is a kind of recording that is easily generated, leading you to frequently delete them and recreate new ones without concerns. You will likely use it for [_requests_](?id=requesting), like fetching Node data. It remembers a real-life [Tape](https://en.wikipedia.org/wiki/Cassette_tape) that is easy to record with a [VCR](https://en.wikipedia.org/wiki/Videocassette_recorder).
+
+**Reel:**
+
+It is a kind of recording that is not so easily generated, leading you to avoid generating them as much as possible. You will likely use it for [_actions_](?id=performing-actions) like paying an Invoice. It remembers a real-life [Film Reel](https://en.wikipedia.org/wiki/Film_stock) that requires a lot of work to [process](https://en.wikipedia.org/wiki/Photographic_processing).
+
+#### Replaying
+
+To create a replayable _Tape_:
+
+```ruby
+public_key = '02d3c80335a8ccb2ed364c06875f32240f36f7edb37d80f8dbe321b4c364b6e997'
+
+data = VCR.tape.replay('lightning.get_node_info', pub_key: public_key) do
+  Lighstorm::Ports::GRPC.lightning.get_node_info(pub_key: public_key).to_h
+end
+```
+
+It will generate a `.bin` file inside `spec/data/tapes/` containing the data [_marshaled_](https://ruby-doc.org/core-3.0.0/Marshal.html).
+
+If you want to force the overwrite of a Tape, replace `replay` with `replay!` Remember to undo it afterward, replacing `replay!` with `replay`.
+
+To create a replayable _Reel_, just do all the same, but replace `VCR.tape` with `VCR.reel`:
+
+```ruby
+response = VCR.reel.replay(
+  'lightning.add_invoice',
+  memo: 'Coffee', value_msat: 1000
+) do
+  Lighstorm::Ports::GRPC.lightning.add_invoice(
+    memo: 'Coffee', value_msat: 1000
+  ).to_h
+end
+```
+
+By understanding its basic operation, you can become creative using [Proc](https://ruby-doc.org/core-3.0.0/Proc.html). Search the code for [`VCR.tape.replay`](https://github.com/icebaker/lighstorm/search?q=VCR.tape.replay&type=code) or  [`VCR.reel.replay`](https://github.com/icebaker/lighstorm/search?q=VCR.reel.replay&type=code) to understand its practical use.
+
+#### Security
+
+Ideally, you will write and run your tests over some Bitcoin [Testnet](https://en.wikipedia.org/wiki/Testnet). There are tools for helping you build a Test Environment like [_Polar_](https://lightningpolar.com).
+
+Regardless, all _Tapes_ and _Reels_ undergo a [sanitization](https://github.com/icebaker/lighstorm/blob/main/spec/helpers/sanitizer_spec.rb) process before being recorded to remove potentially dangerous (like `payment_preimage`) or privacy-exposing (like `payment_addr`) data. All data potentially [unsafe](https://github.com/icebaker/lighstorm/blob/main/spec/helpers/sanitizer/unsafe.rb) is replaced by randomly generated data of equivalent type and size. If unknown data emerges, it needs to be classified as [safe](https://github.com/icebaker/lighstorm/blob/main/spec/helpers/sanitizer/safe.rb) or [unsafe](https://github.com/icebaker/lighstorm/blob/main/spec/helpers/sanitizer/unsafe.rb). Otherwise, it will be impossible to be recorded, generating an [error](https://github.com/icebaker/lighstorm/blob/main/spec/helpers/sanitizer.rb#L102).
+
+### Contracts
+
+Sometimes you are interested in testing the _shape_ of something instead of its _content_. Symptoms of this appear when you change something in your code and have to mechanically fix dozens of tests because of a minor thing that doesn't make a real difference to what you are testing. This may lead you to avoid doing some important changes because it will be too boring to fix the tests.
+
+It usually plays like this:
+
+```ruby
+expect(something.to_h).to eq(
+  { created_at: '2023-02-26 15:01:45 UTC',
+    title: 'Coffee',
+    price: 1000 }
+)
+```
+
+And then you change something, and it breaks multiple tests because `'2023-02-26 15:01:45 UTC'` becomes `'2023-02-26 15:03:29 UTC'` and `1000` becomes `950`.
+
+You already have other tests ensuring that the `created_at` and `price` are correct, and in this specific test, you just want to ensure that `to_h` generates the expected output _shape_.
+
+So after patiently spending hours and hours fixing these little unimportant changes, you give up on creating new tests like these and eventually even deleting the old ones because it's too much work to maintain them, reducing your test coverage.
+
+Well, this is happening because you are testing the **wrong** thing. You don't care about each minimal bit of the content in this test, only its _approximate shape_. This is similar to the idea of a [_Contract Test_](https://martinfowler.com/bliki/ContractTest.html).
+
+To ensure that writing tests will be as painless as possible, we have a [helper for testing _contracts_](https://github.com/icebaker/lighstorm/blob/main/spec/helpers/contract_spec.rb):
+
+```ruby
+expect(Contract.for(something.to_h)).to eq(
+  { created_at: 'String:21..30',
+    price: 'Integer:0..10',
+    title: 'String:0..10' }
+)
+```
+
+That's it. No matter the date, your test will pass as long as `created_at` is a `String` between 21 and 30 characters.
+
+Also, sometimes you end up with a test that contains a `Hash` with 100+ lines. While it's good to have the contract visible when it's short, if it's too long, we can just use a [hashed version](https://en.wikipedia.org/wiki/Hash_function) of the contract to ensure that it's not being broken:
+
+```ruby
+Contract.expect(
+  something.to_h, '77b0c3a51abe6'
+) do |actual, expected|
+  expect(actual.hash).to eq(expected.hash)
+  expect(actual.contract).to eq(expected.contract)
+end
+```
+
+It will generate a `.bin` file inside `spec/data/contracts/` containing the contract [_marshaled_](https://ruby-doc.org/core-3.0.0/Marshal.html), and if it changes, the `77b0c3a51abe6` hash will change, and your test will fail.
+
+Inside the block, you can inspect the actual data with `actual.data`. For generating a contract for the first time, use `expect!` with a `nil` hash:
+
+```ruby
+Contract.expect!(
+  something.to_h, nil
+) do |actual, expected|
+  expect(actual.hash).to eq(expected.hash)
+  expect(actual.contract).to eq(expected.contract)
+end
+```
+
+Your contract will be generated, and you can get its hash from the `rspec` output:
+
+```ruby
+expected: nil
+     got: "77b0c3a51abe67133e981bc362430b2600d23200e9b3b335c890a975bda44575"
+```
+
+Remember to undo it afterward, replacing `expect!` with `expect`.
+
+## Generating Documentation
+
+```sh
+npm i docsify-cli -g
+
+docsify serve ./docs
+```
+
+## Publish to RubyGems
+
+```sh
+gem build lighstorm.gemspec
+
+gem signin
+
+gem push lighstorm-0.0.8.gem
+```
+
 _________________
 
 <center>
-  lighstorm 0.0.6
+  lighstorm 0.0.8
   |
   <a href="https://github.com/icebaker/lighstorm" rel="noopener noreferrer" target="_blank">GitHub</a>
   |