Cardano Wallet Backend - Wallet Management

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-launcher	linux-x86_64	A commodity utility to launch a wallet server with a corresponding node backend.

Key Features

This release contains support for basic wallet management features via web
server (JSON through HTTP) or a command-line interface.

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 mnemonic sentence (english) of various sizes

• 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

cardano-wallet-launcher

• A command-line interface which starts and supervise both a wallet server and a cardano-http-bridge

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).

• ⚠️ The wallet backend server is shipped with only an in memory storage which is volatile: restarting the server will erase the memory completely.

Known Issues

Ticket	Title
#250	GET v2/wallets does not list wallets from oldest to newest
#291	Shuffle statistical tests sometimes fail...

Bug Fixes

• N/A

Installation Instruction

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

1. Install cardano-http-bridge.

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

2. Download cardano-wallet and cardano-wallet-launcher 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 cardano-wallet-launcher

3. Start cardano-wallet-launcher --help and see available parameters and follow instructions about how to install cardano-http-bridge if you haven't done already in point 1.

NOTE:

The wallet server & launcher both expect a NETWORK ENV var to be available with one of the following value:

• mainnet
• testnet
• staging (not supported)

This variable commands which network the software should connect to and interact with.

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

Wallet Layer Integration (with cardano-http-bridge)

PR	Description
#88	Add property tests for the database layer
#97	Fix typo in http-bridge tests
#98	Increase test coverage for http-bridge integration
#115	Technical debt: add unit tests for network and wallet layer
#132	Http-bridge with a local cluster in integration tests
#134	Move test data archives
#135	Get cardano-node-simple available in CI & allow manipulating stream output when launching commands
#149	Prevent network layer to "die" when node backend fails
#153	Better test coverage for 'Network.listen'
#179	Runtime network configuration as ENV var
#193	Provide clearer failure reason when wallet is not syncing
#202	Redirect launcher, wallet & bridge output to temporary files during integration tests
#205	Review high-level interfaces ('IsOurs', 'IsOwned', 'GenChange') to be more granular
#207	Parameterize wallet core over the 'TxId' format
#210	Parameterize wallet core over the 'Address' format
#212	Code re-organization: Extract Http-bridge specifics into a dedicated package
#226	Make integration tests failing with a clear message on mainnet and staging

Restore Historical Data

PR	Description
#137	Add tracking of known transactions to the wallet model
#150	Store transaction history outside of the wallet state
#156	Wallet Id deterministic calculation from root public key
#158	Extend DB layer & wallet to support wallet metadata
#172	Unify 'watchWallet', 'listen', 'processWallet', 'tick' etc.. into one 'restoreWallet'
#180	Implement some missing API handlers for the wallets endpoints
#234	Fix 'slotRatio' case where the numerator is further than the denominator

Benchmarking & Nightly Builds

PR	Description
#120	Remove unused semigroup instance for address pools
#157	Add restore benchmarks
#160	Add new "special" address discovery scheme (proportional ownership) for testing and benchmarking
#169	Fix benchmarks on Buildkite after last refactor
#187	Add buildkite nightly build badge (and link) to README
#190	Move ENV var export from buildkite script to buildkite pipeline settings

Coin Selection, transaction creation & submission

PR	Description
#114	Model transaction metadata as a type
#121	Add types skeleton of coin selection and largestFirst algo implementation
#130	Extend network-layer to support sending transaction + implement interface with HTTP bridge
#140	Random input selection re-implementation
#146	Few more negative tests for submitting transactions to cardano-http-bridge
#164	Scaffold wallet layer for transaction creation
#166	Add signing module to generate witnesses for standard (not multi-sig) transactions
#167	Review network layer error (more consistent with other interfaces)
#175	Passphrase primitives (encryption & check)
#181	Keystore interface extension for our DB-layer
#182	Implement POST /v2/transactions API handler
#196	Improve testing & coverage for coin selection & fee calculation
#201	Property-based tests for 'shuffle' from the coin selection
#203	Golden tests for signing of transactions (comparing with cardano-sl)
#211	Introduce a 'TransactionLayer' to isolate bits related to transaction signing & size estimation

Fee Calculation

PR	Description
#174	Split Fee-related logic from CoinSelection
#176	Realistic Fee Calculation (Byron)
#196	Improve testing & coverage for coin selection & fee calculation
#199	Adjust transaction for fee after coin selection

Initial Wallet Backend Server & Corresponding CLI

PR	Description
#76	Translate a subset of the wallet API specification into Servant
#83	Port integation tests request module from the old codebase
#102	Use hspec-golden-aeson for automatic API golden and roundtrip tests for API types
#104	Integration tests DSL extensions: ability to assert on an API response code
#106	Few negative mnemonic test cases
#107	Finalize First API types
#108	Automatic property-based test to validate API Servant definition against swagger specification
#111	Add servant post transaction endpoint
#119	Servant API: post wallet operation
#123	Fix language usage within comments
#124	Encode minimum and maximum length for values just once
#125	Add ListAddresses, PutWallet, PutWalletPassphrases to servant API definition
#127	API server foundation
#128	Add a few negative test cases for api types specs for instances that aren't fully generic
#131	Integration tests DSL extensions: ability to send non-valid JSON payload in the request
#133	Add foundation & initial implementation for a full-blown wallet CLI
#136	Api smart constructors
#139	Fixes in API specification: use 'block' as a unit instead of 'slot'
#141	JSON roundtrip and golden for signed tx type
#142	Add FromText and ToText classes to Api.Types
#152	Few tests for 'FromText' instances
#155	Implement 'cardano-wallet server' command to spin up an actual server
#159	Fix comments in Data.Text.Class to remove any mention of the API
#161	Add roundtrip textual encoding tests for Network and Port CLI types
#163	Negative cases for API types decoding
#170	First integration tests on create wallet API endpoint
#177	Promote 'ChangeChain' from the term-level to type-level on 'AddressPool'
#178	Rename Change Interface & Store new state after generating change addresses
#183	Replace 'OctetStream' content-type in API with a proper 'Any' placeholder for response without content
#184	More consistency between API specification and automated API testing
#185	Integration tests DSL extensions (more expectations & teardown after test)
#188	Remove CLI message about passphrase that can be skipped
#189	Finalize CLI implementation for endpoints in scope
#191	Few unit tests for 'Cardano.Environment'
#194	First integration scenarios for wallet creation
#195	Include protocol magic in address attributes for testnet
#197	Better error messags for mnemonic creation errors
#198	Property-based tests for change address generation
#200	Fixes in API specification: passphrase length & error code 406
#209	Remote tx history from the wallet state, and replace some usage of 'Set' with built-in 'List'
#214	use 'FromText' instance in the API for 'AddressPoolGap'
#221	Integration scenarios for wallet creation: address pool gap
#228	Rename 'ApiCoins' to 'AddressAmount'
#230	Fix API definitions for addresses (which fix request routing for GET /v2/wallets/{walletId})
#232	Review CLI interface & implement --version
#235	Integration tests for 4xx with wallet management API

Miscellaneous

PR	Description
#99	Add more information to README
#105	Show pre-releases in README badges
#109	Remove non-breaking space characters from source code
#112	Modules renaming to align with underlying code architecture
#113	Fix haddock exports failure on CI
#117	Tidy code to meet coding standards
#206	Review folder organization
#208	Code re-organization: change test data location
#213	Code re-organization: CoinSelection & Fee as primitives
#215	Code re-organization: change test data location (again)
#222	Review and cover 'Buildable' instances for primitive types
#223	Compute code coverage for integration test scenarios
#224	Fix 'fromText' instance for 'Int'
#231	New take on Data.Quantity documentation
#233	Relax a bit QuickCheck constraints on 'shuffle' properties
#236	Better test coverage for API types (roundtrip HttpApiData, missing negative tests...)
#237	Use a lower statistical confidence for 'shuffle' properties