Cardano Wallet Backend - Logging & SQLite

Overview

Program	Platform	Description
cardano-wallet	linux-x86_64	A CLI tool to start and interact with a wallet server. See Key Features below.
cardano-wallet.sh	linux-x86_64	Auto-completion script for cardano-wallet

This release tries to close the gap for allowing Daedalus to start integrating with the wallet backend. It also comes bundled with an SQLite persistence layer to allow saving to disk the wallet state. On the way to testnet and mainnet releases, we have also introduced better structured logging in this release, with some degrees of control regarding the verbosity of the software.

We have simplified a bit the software organization and merged together cardano-wallet and cardano-wallet-launcher in a single binary cardano-wallet. The launcher is now available as a launch command.

⚠️ This release contains a critical issue regarding wallet restoration (see #484).

This issue is fixed in v2019-07-02.

Main Features

cardano-wallet

• A command-line interface which exposes the following features (see CLI manual below):

  • Create and Delete wallet
  • Get details of a particular wallet
  • List all known wallets
  • Generate BIP-39 mnemonic sentence (english) of various sizes
  • Update wallet metadata
  • Create and submit transactions from a single wallet
  • List known (used or unused) addresses of a wallet
  • --state option for cardano-wallet address list
  • serve command (replaces server ⚠️ breaking-change ⚠️)
  • launch command (replaces cardano-wallet-launcher ⚠️ breaking-change ⚠️)
  • --state-dir option for cardano-wallet launch
  • --database option for cardano-wallet serve
  • --random-port option for cardano-wallet launch and cardano-wallet serve
  • --quiet and --verbose options for cardano-wallet launch and cardano-wallet serve

• A web server which exposes the following features (see API Documentation below):

  • Create and Delete wallet
  • Get details of a particular wallet
  • List all known wallets
  • Update wallet metadata & wallet encryption passphrase
  • Create and submit transactions from a single wallet
  • List known (used or unused) addresses of a wallet
  • Filter addresses by state (used or unused)
  • SQLite backend to persist the wallet state to disk!
  • API request / response logging
  • Database debug logs
  • (Partial) application-level logs

• Node.js-compatible IPC server with custom protocol

Known Limitations

• ⚠️ Only one address derivation scheme is supported: sequential scheme (a.k.a. Icarus' address style or, addresses à la BIP-44).

• ⚠️ So far, only one backend is supported: cardano-http-bridge (run on the Byron-OFT era, experimental stability).

Bug Fixes

Ticket	Title
#250	GET v2/wallets does not list wallets from oldest to newest
#260	No additional error message in case of 4xx responses
#324	Bech32 occassionally fails when decoding a string with an omitted character
#326	Cannot post transaction after updating wallet's passphrase
#333	Sending transaction to not-valid address (yet being base58 encoded string) gives HTTP 500 -> "Something went wrong"
#364	Transaction with amount 0 on http bridge fails with error HTTP 500
#397	CLI wrongly returns exit code 0 when providing not existing wallet id
#398	CLI unnecessarily asks for password when posting transaction from a non-existing wallet
#403	API swagger specification isn't a valid swagger file

Known Issues

Ticket	Title
#409	cardano-wallet server fails with unpleasant error when does not connect to http-bridge within a few seconds
#423	Starting mainnet server on testnet bridge results in unfriendly error message.
#484	Restoration workers aren't restarted with the server

Installation Instruction

Please note that currently only Unix\Linux platform is supported.

1. Install cardano-http-bridge from our fork.

   • Install the rust toolchain.
   • In terminal run cargo install --git https://github.com/KtorZ/cardano-http-bridge.git --branch cardano-wallet-integration
   • make sure $HOME/.cargo/bin is on your $PATH

2. Download cardano-wallet and put it in the directory that is on your $PATH, e.g. /usr/local/bin. Make sure to add exec permissions on binary files:

   • chmod u+x cardano-wallet

3. Start cardano-wallet --help and see available parameters.

Documentation

Link	Audience
API Documentation	Users of the Cardano Wallet API
Haddock Documentation	Haskell Developers using the cardano-wallet as a library
CLI Manual	Users of the Cardano Wallet API

Changelog

SQLite implementation for the DB Layer

PR	Description
#259	Generate DBLayer tests with quickcheck-state-machine
#337	Sqlite: add more locking to DBLayer methods
#341	Sqlite: Initial benchmark for putTxHistory
#347	Sqlite: use repsertMany instead of deleteMany+putMany
#348	Sqlite benchmark: Use a file-based DB
#349	Some small fixes to DB.StateMachine module.
#360	Sqlite: Fix deletion for larger numbers of checkpoints/transactions
#367	Make DB QSM tests fail if one or more tags are not covered.
#370	Recreate passing tests and file-based and in-memory runQuery
#377	cli: Add "local" network to launcher, and --state-dir for the database
#378	Clean ups of Sqlite test code
#379	Use SQLite in restoration benchmark (instead of MVar implementation)
#406	Use SQLite in integration tests scenarios (instead of MVar)
#413	Additional tests checking if files exists when using --database and --state-dir options

Jörmungandr Integration

PR	Description
#310	Add Jörmungandr Servant Api Type
#313	Address Format in Shelley Era (Part 1: abstract over the address encoding)
#321	Jormungandr m with getTipId implementation
#322	Simplify folder structure, e.g. s/Binary.HttpBridge/HttpBridge.Binary/
#323	Miscellaneous Bech32 library fixes and improvements.
#325	Add Cardano.Wallet.Jormungandr.Network.Api
#327	Add extra debugging information to Bech32 decoding corruption tests.
#328	Add known-to-fail counterexamples to Bech32 string corruption tests.
#329	move Cardano.Environment.{HttpBridge,Jormungandr} to Cardano.Wallet.{HttpBridge,Jormungandr}.Environment
#332	Fix the Bech32 character mutation test.
#336	Address Format in Shelley (Part 2: implementing address encoder and decoders + tests)
#338	Fix index limits in Bech32 mutation tests
#340	Strengthen the precondition for the Bech32 mixed-case mutation test.
#362	Add initial support for serializing signed transaction
#369	Implement Jörmungandr getBlock and getDescendants
#382	review & fix jormungandr configuration to enable block production in BFT mode
#383	Jörmungandr: mkNetworkLayer with networkTip
#384	Change wallet currentTip from SlotId to BlockHeader
#385	Add labels to binary decoders for improved debugging
#394	Handle getBlockHeader special cases for proofs
#396	Relocate reusable integration tests components to core
#400	Preliminary integration tests between Jormungandr <-> Network Layer (networkTip)
#405	Implement NetworkLayer getNext for Jörmungandr
#417	Jörmungandr: Separate concern between keyToAddress and get/putAddress
#424	Creating faucet for jormungandr
#435	Adapt CompatibilitySpec goldens to use & test singleAddressFromKey
#436	Implement jörmungandr txId
#437	newTransactionLayer for Jormungandr
#439	Implement Jörmungandr TransactionLayer
#451	Parameterize Tx data-type over the wallet core engine (allowing to work with different representations)
#452	Review transaction ids golden tests (only new addresses)
#454	Integration Test Scenarios on top of Jörmungandr (Initial Setup)

List Addresses

PR	Description
#335	Integration tests for list addresses and transactions (api)
#344	Make the listWallets API call return wallets in ascending order of creation time.
#395	Integration tests for list addresses with filtering and outstanding list addresses tests via CLI

Integrate node.js IPC listener in the launcher

PR	Description
#372	Allow filtering by address state when fetching all addresses
#387	server: Listen on unused TCP port selected at random
#388	Adapt NodeIPC module from cardano-sl
#399	Small adjustment in CLI
#414	Merge 'cardano-wallet-launcher' & 'cardano-wallet' together
#446	Additional tests for IPC connection with various port options

Logging

PR	Description
#390	Add basic infrastructure for logging.
#412	Provide a way to specify a minimum log severity level through the CLI.
#420	Remove manually-defined Bounded instance for Severity.
#421	Write version string to the log when starting the wallet server.
#430	Api Logger Middleware (Part I: request & response logging with sanitization)
#432	Api Logger Middleware (Part II: request id and timestamping)
#438	Api Logger - Log 500+ as ERROR instead of INFO
#441	Api Logger Middleware - Unit tests
#443	stack.yaml: Add flags to reduce iohk-monitoring dependencies
#449	tests: Add a small test of Sqlite logging
#450	Replace CLI --min-log-severity argument with --quiet and --verbose switches.

Miscellaneous / Technical Debts

PR	Description
#103	Allow build with nix-tools.
#334	Rough Idea: Replace NETWORK=testnet with HttpBridge 'Testnet
#342	add little delay to allow sockets to be cleaned up after the launcher specs
#343	Update API spec with 405 code and add tests against 405 for remaining endpoints
#346	Reorganize integration tests for better clarity and trackability of CLI tests
#363	Fix tx builder in fee calculation property
#365	Transaction tests via CLI
#373	cli: Use Paths module to get program version
#375	bors: Disable branch sniping
#376	Fix a tiny typo in the CLI help text.
#389	Fix the build by making use of the NamedFieldPuns extension.
#392	Remove 'staging' network target
#393	move class-constraints further down into the wallet layer interface
#404	Small test tweaks for enhanced speed & coverage
#415	add missing extra-deps for 'binary' in stack.yaml
#416	reduce usage of 'fixtureWallet' in the integration tests
#434	Remove boilerplate from ToText and FromText instances.
#447	wait for network to be ready in benchmarks ...
#453	another attempt trying to cope with 500 when fetching network tip shortly after init (bridge)
#455	bump version to 2019.6.24, preparing next release
#456	bump revision for iohk-monitoring-framework

Bugs - Sprint 21-22 & Sprint 23-24

PR	Description
#330	Oversight: re-encrypt wallet root private key with provided passphrase when updating it....
#381	Review all uses of (Passphrase seed), add PassphraseMinMaxLength inst…
#407	Fix CLI port argument bug.
#408	Fix syntax errors in Api swagger specification + automated syntax check in CI
#425	Better --port & --bridge-port options validation in CLI
#445	add ErrInvalidTx to capture Quantity=0 situation in Byron (http-bridge)

Signatures

Name	Role	Approval
Matthias Benkort @KtorZ	Technical Team Lead	✔️
Piotr Stachyra @piotr-iohk	QA Engineer	✔️
Tatyana Valkevych @tatyanavych	Release Manager	✔️