Problem Summary:

While developing blockchain software, how can we cheaply find and fix errors in logic code that executes near expensive blockchain calls?




Problem Description:

1) A blockchain application will create blockchain transactions. These transactions, once they settle, are irreversible. They are essentially "signed API calls" to a blockchain. If and when they settle, they will permanently alter that blockchain's state. A blockchain can be thought of as a write-only external API.

2) Inside a blockchain application, there will be important functions (e.g. "createWithdrawal") that do a lot of work - designing, creating, storing, and broadcasting a transaction.

3) Developing new code that will fit into this work sequence is necessary, but also difficult to test. Naively, the entire work sequence is run in order to test the new section of code. Mistakes are expensive and irreversible.

4) Calls to databases can also be expensive. An incorrect database call can create messy data that is very time-consuming to rectify.

5) Calls to external APIs can also be expensive. They may count against a paid monthly limit. And, similarly to database calls, an incorrect API call can create messy data on the company account on the external service that is very time-consuming to rectify.




Development Strategy:

- We treat all blockchain transactions, database calls, and API calls as "external calls". [0]

- An external call occurs in its own function, which can be tested separately. This is called an "edge function". All edge functions should have timeouts and failure handling.
-- Output data can be recorded, and later used as input data when testing other functions.

- A function that calls an edge function is called a "blend function". It may call multiple edge functions and / or various logic functions.
-- Almost no logic takes place within a blend function. We permit only assignments, function calls, error-handling decisions, and logging actions.
-- Even a single syntax error can be expensive to locate and fix if external calls occur during the function. This is why we avoid logic in blend functions (unless the edge functions only retrieve data). It's possible to mock the edge functions, but this can be time-consuming. Putting all logic into separate logic functions for unit-testing is the cheapest way to detect, locate, and fix errors within the logic code, especially during continuous application development.

- A function that only performs logic operations is called a "logic function". A function that only calls other logic functions is also a logic function.

- Unit tests can be written for logic functions.

- End-to-end / behavioural tests can be written for blend functions.
-- Mock functions can be written and substituted for any edge functions. Mock functions will return output data that was previously recorded.

- Edge functions are tested manually, using a cmd-line tool (logging at DEBUG level).
-- The output data can be stored for later use as test input to other functions.
-- For database edge functions, it's also possible (although time-consuming) to write tests that spin up a new database, populate it with data, run the edge function, and check that the data in the database is now in the expected final state.
-- For blockchain edge functions, it's also possible (although time-consuming) to write tests that spin up a tiny standalone version of the relevant blockchain, populate it with data by executing transactions, run the edge function, and check that the data in the blockchain is now in the expected final state.
-- Edge functions that solely retrieve data can be tested with unit tests. These are database SELECT functions, external API GET functions, and blockchain loadTransaction / loadBlock functions.




Tactics:

- Use argument validation. For crucial functions, this should be very strict.

- Use named arguments where possible, not positional ones. This is very helpful when you later add or subtract arguments from functions.

- Each module (i.e. file) has its own named logger. This is expensive to set up but extraordinarily helpful for diagnosing problems.

- Ideally, loggers are namespaced by filename and path (e.g. they contain something similar to "[appName/chainOps/foo.js]" somewhere in the line) and contain the relevant function name and line number. They are configurable by parent modules (i.e. a parent module can set a child module's log level). Options: Colorised output, an initial timestamp. Log level names (e.g. DEBUG, INFO) should all be padded to the same length. Optionally, the logger logs to a file, with a rolling window (e.g. 30 days). If multiple processes are logging to the same file, use a uniqueID in each log line to differentiate between each output stream.

Here's a couple example log lines:


- All external functions return the same thing: A 'result' object containing 'err' and 'msg' properties and various other data properties.
-- The data properties depend on the function. They should always be present, even if empty.
-- The 'err' property should always be present, even if empty.
-- The 'msg' property contains a message string that describes the result of the function. This is helpful for logging. It can be an empty string.
-- The 'err' property is an object that contains 'code' and 'msg' properties.
--- The 'code' property contains the error code, which permits complex error handling in caller functions. If this is 0, then no error occurred. Always set it to a non-zero value at the start of a function, so that the function only completes successfully if certain conditions are explicitly achieved.
--- The err.msg property contains an optional error message, which is helpful for logging and for throwing informative Errors.

- At first, we handle errors by throwing them. They are caught and reported in try / catch clauses.
-- Over time, check for common errors and return them within the result object. The caller function can then select an appropriate action to take in response to the error.




Let's do an example.




Here is a NodeJS function called . This is new code, written for this article as an illustration. It has not been tested. Most of the called functions are not shown.