Path to multi-sig and multi-asset

This release is a step towards supporting multi-signature script addresses. It contains several fixes to reduce false negatives in our test suite, so that we can work faster. The codebase is being prepared for the multi-asset Cardano era.

Compatible with [email protected].

New Features

• Add CLI option for setting transaction TTL #2267
• Allow deleting expired transactions from the API #2262
• Allow creating multi-signature script addresses using the POST /v2/addresses endpoint #2253 #2318
  • ⚠️ BREAKING-CHANGE GET /wallets/{walletId}/keys/{role}/{index} now returns naked public keys (without chain code).
• Update cardano-addresses to 3.1.0 as part of the ongoing work to support multi-signature script addresses #2317

Improvements

• cardano-wallet-jormungandr is now a separate GitHub repository, and the Jörmungandr backend has been removed from this release #2284 #2313
• Refactor the Hash type as part of ongoing work to support multi-asset wallets #2303

Resolved Issues

• Get correct values of epoch and slot length for /v2/network/parameters by using the HFC History Interpreter #2246
• Revise API error codes for the transactions API #2293
• Garbage collect delisted stake pools from SMASH #2249 #2309 #2314
  • There's now a new field called flags attach to each stake pool. It can be an empty array, or a singleton array with the string "delisted" if the pool is marked as delisted from a configured SMASH server/
• Additional testing of runtime modification to the stake pool metadata source #2225
• Make nix-shell evaluation faster #2300

Quality improvements

• Use the new openapi3 package to improve OpenAPI tests #2289
• Fix nightly DB migration tests #2302
• Add script for analysing bors CI failures #2306
• Run integration tests in parallel #2191 #2297
• Fix wrong setup/expectation in TRANS_CREATE_03 #2299

Known Issues

• Concurrent requests to the cardano-wallet will cause sqlite to return error and enpoints return non-json error messages #2280
• Incorrect mainnet network parameters returned from API #2226
• Estimating fees on empty Shelley wallet takes 5-6 s #2170
• nix-build -A cardano-wallet fails on macOS Big Sur #2070
• Cannot send funds from Byron random address created via cardano-address #2058
• Balance temporarily increases when spending rewards #1955
• Required wallet DB fields do not get persistently added #1743
• cardano-wallet address CLI has import and create commands which are not supported for Shelley wallets #1733

Documentation

• API Documentation
• CLI Manual
• Docker Manual

Installation Instructions

1. Install [email protected].

2. Download the provided cardano-wallet for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

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

Docker

Pull from DockerHub and verify the version matches 2020.11.17.

$ docker pull inputoutput/cardano-wallet:2020.11.17-shelley
$ docker run --rm inputoutput/cardano-wallet:2020.11.17-shelley version

Signatures

Name	Role	Approval
Matthias Benkort @KtorZ	Technical Team Lead	✔️
Piotr Stachyra @piotr-iohk	QA Engineer	✔️
Laurence Jenkins @LaurenceIO	Release Manager	✔️

Hardware Wallets Extensions

Compatible with [email protected] and [email protected].

New Features

• Added an (experimental) endpoint for standalone transaction metadata signing #2257 #2274 #2269 #2263
• Added an endpoint for performing soft-derivation of wallet keys #2229 #2266
• Extended the coin-selection API to support selecting coins for delegation #2213
• Added time-to-live parameter to the Shelley payments API #2167
• Added an endpoints for dynamic configuration of stake pool metadata fetching strategies #2241 #2285 #2277 #2270

Improvements

• Distinguished change outputs from requested outputs as two separate fields in coin-selection #2244
• Added deprecation disclaimer for random wallet restoration #2283
• Updated the API specification to reflect the minimum number of inputs returned by selectCoins API #2261
• Added parallel wallet restoration benchmarks for N={1,10,20,40,80,100} wallets #2243 #2260
• Documented endpoints error codes in the API documentation #2258

Resolved Issues

• Fixed address prefixes on testnet #2273

Known Issues

• Concurrent requests to the cardano-wallet will cause sqlite to return error and enpoints return non-json error messages #2280
• Incorrect mainnet network parameters returned from API #2226
• Estimating fees on empty Shelley wallet takes 5-6 s #2170
• Jormungandr doesn't complain about invalid block0.bin #2187
• cardano-wallet-jormungandr --metadata option is redundant #2169
• No rewards from staking for wallets on Jörmungandr node #2140
• nix-build -A cardano-wallet fails on macOS Big Sur #2070
• Cannot send funds from Byron random address created via cardano-address #2058
• Balance temporarily increases when spending rewards #1955
• Required wallet DB fields do not get persistently added #1743
• cardano-wallet address CLI has import and create commands which are not supported for Shelley wallets #1733

Documentation

Cardano (cardano-node)	ITN (Jörmungandr)
API Documentation	API Documentation
CLI Manual	CLI Manual
Docker Manual	Docker Manual

Installation Instructions

Cardano (cardano-node)

1. Install [email protected].

2. Download the provided cardano-wallet for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

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

Docker

Pull from DockerHub and verify the version matches 2020.11.3.

$ docker pull inputoutput/cardano-wallet:2020.11.3-shelley
$ docker run --rm inputoutput/cardano-wallet:2020.11.3-shelley version

ITN (jormungandr)

1. Install [email protected].

2. Download the provided cardano-wallet-jormungandr for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

3. (optional) Install the bash/zsh auto-completion script according to the jormungandr cli manual

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

Docker

Pull from DockerHub and verify the version matches 2020.11.3

$ docker pull inputoutput/cardano-wallet:2020.11.3-jormungandr
$ docker run --rm inputoutput/cardano-wallet:2020.11.3-jormungandr version

Signatures

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

Configurable SMASH

Compatible with [email protected] and [email protected].

New Features

• Added the ability for users to select their own SMASH servers for stakepool listings #2214
• Added transaction expiry slots for pending transactions #1879

Improvements

• Extended isOurs to return the derivation path of an address #2219
• Added a 100-wallet scenario to the latency benchmark #2223
• Added an executable shelley-test-cluster which starts an integration test cluster that includes faucets #2178

Resolved Issues

• Made pool garbage collection handle an unknown current epoch #2203

Known Issues

• Incorrect mainnet network parameters returned from API #2226
• Estimating fees on empty Shelley wallet takes 5-6 s #2170
• Jormungandr doesn't complain about invalid block0.bin #2187
• cardano-wallet-jormungandr --metadata option is redundant #2169
• No rewards from staking for wallets on Jörmungandr node #2140
• nix-build -A cardano-wallet fails on macOS Big Sur #2070
• Cannot send funds from Byron random address created via cardano-address #2058
• Balance temporarily increases when spending rewards #1955
• Required wallet DB fields do not get persistently added #1743
• cardano-wallet address CLI has import and create commands which are not supported for Shelley wallets #1733

Documentation

Cardano (cardano-node)	ITN (Jörmungandr)
API Documentation	API Documentation
CLI Manual	CLI Manual
Docker Manual	Docker Manual

Installation Instructions

Cardano (cardano-node)

1. Install [email protected].

2. Download the provided cardano-wallet for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

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

Docker

Pull from DockerHub and verify the version matches 2020.10.13.

$ docker pull inputoutput/cardano-wallet:2020.10.13-shelley
$ docker run --rm inputoutput/cardano-wallet:2020.10.13-shelley version

ITN (jormungandr)

1. Install [email protected].

2. Download the provided cardano-wallet-jormungandr for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

3. (optional) Install the bash/zsh auto-completion script according to the jormungandr cli manual

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

Docker

Pull from DockerHub and verify the version matches 2020.10.13

$ docker pull inputoutput/cardano-wallet:2020.10.13-jormungandr
$ docker run --rm inputoutput/cardano-wallet:2020.10.13-jormungandr version

Signatures

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

Syncing performance improvements & Address inspection

Compatible with [email protected] and [email protected].

New Features

• Allow address inspection via the API #2184

Improvements

• Up to 2x faster restoration of very large wallets: cache latest checkpoint in-memory to avoid deserializing and reserializing it too often. #2161
• Add shell completions (bash, zsh, fish) to release binary artifacts #2107
• Allow to build with cabal #2027

Resolved Issues

• Save intermediate state when restoring the Byron chain in the stake pools worker #2138
• Make API version in swagger.yaml updated on every release #2190
• Make addresses separate category in swagger #2185
• Fix embarrassing spelling #2179
• Add fallback for metadata JSON parsing from pre-existing database #2173
• Fix metadata examples in swagger.yaml #2171

Known Issues

• Estimating fees on empty Shelley wallet takes 5-6 s #2170
• Jormungandr doesn't complain about invalid block0.bin #2187
• cardano-wallet-jormungandr --metadata option is redundant #2169
• No rewards from staking for wallets on Jörmungandr node #2140
• nix-build -A cardano-wallet fails on macOS Big Sur #2070
• Cannot send funds from Byron random address created via cardano-address #2058
• Balance temporarily increases when spending rewards #1955
• Required wallet DB fields do not get persistently added #1743
• cardano-wallet address CLI has import and create commands which are not supported for Shelley wallets #1733

Documentation

Cardano (cardano-node)	ITN (Jörmungandr)
API Documentation	API Documentation
CLI Manual	CLI Manual
Docker Manual	Docker Manual

Installation Instructions

Cardano (cardano-node)

1. Install [email protected].

2. Download the provided cardano-wallet for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

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

Docker

Pull from DockerHub and verify the version matches 2020.9.30.

$ docker pull inputoutput/cardano-wallet:2020.9.30-shelley
$ docker run --rm inputoutput/cardano-wallet:2020.9.30-shelley version

ITN (jormungandr)

1. Install [email protected].

2. Download the provided cardano-wallet-jormungandr for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

3. (optional) Install the bash/zsh auto-completion script according to the jormungandr cli manual

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

Docker

Pull from DockerHub and verify the version matches 2020.9.30

$ docker pull inputoutput/cardano-wallet:2020.9.30-jormungandr
$ docker run --rm inputoutput/cardano-wallet:2020.9.30-jormungandr version

Signatures

Name	Role	Approval
Johannes Lund @Anviking	Technical Team Lead Replacement	✔️
Piotr Stachyra @piotr-iohk	QA Engineer	✔️
Matthias Benkort @KtorZ	Release Manager Replacement	✔️

Improvements to Transaction Metadata & Pool Metrics

Compatible with [email protected] and [email protected].

New Features

• CLI support for creating transactions with metadata #2125

Improvements

Breaking changes

• POST /wallets/{walletId}/transactions uses a new scheme for metadata, ensuring that API users will always see exactly the same JSON in the transaction history and cardano explorer as what they submitted with the transaction. #2147
• Subtly improved metrics from GET /stake-pools #2162, IntersectMBO/cardano-ledger#1854
  • relative_stake and saturation are now based on a pool's current stake instead of a past snapshot. The same is true for the saturation used to calculate non_myopic_member_rewards. This makes non_myopic_member_rewards immediately respond to over-saturation.
  • relative_stake is now relative to the total stake, instead of the active stake

Other changes

• Improved API documentation for transaction metadata #2157
• Removed unnecessary checkpoints from the database #2143

Resolved Issues

• The reported value of saturation is incorrect #1980
• Fix dylib references of bundled programs on macOS #2135

Known Issues

• Estimating fees on empty Shelley wallet takes 5-6 s #2170
• Stake pool DB worker progress is only saved if it is allowed to reach Shelley in a single session #1963
• cardano-wallet-jormungandr --metadata option is redundant #2169
• No rewards from staking for wallets on Jörmungandr node #2140
• nix-build -A cardano-wallet fails on macOS Big Sur #2070
• Cannot send funds from Byron random address created via cardano-address #2058
• Balance temporarily increases when spending rewards #1955
• Required wallet DB fields do not get persistently added #1743
• cardano-wallet address CLI has import and create commands which are not supported for Shelley wallets #1733

Documentation

Cardano (cardano-node)	ITN (Jörmungandr)
API Documentation	API Documentation
CLI Manual	CLI Manual
Docker Manual	Docker Manual

Installation Instructions

Cardano (cardano-node)

1. Install [email protected].

2. Download the provided cardano-wallet for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

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

Docker

Pull from DockerHub and verify the version matches 2020.9.22.

$ docker pull inputoutput/cardano-wallet:2020.9.22-shelley
$ docker run --rm inputoutput/cardano-wallet:2020.9.22-shelley version

ITN (jormungandr)

1. Install [email protected].

2. Download the provided cardano-wallet-jormungandr for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

3. (optional) Install the bash/zsh auto-completion script according to the jormungandr cli manual

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

Docker

Pull from DockerHub and verify the version matches 2020.9.22

$ docker pull inputoutput/cardano-wallet:2020.9.22-jormungandr
$ docker run --rm inputoutput/cardano-wallet:2020.9.22-jormungandr version

Signatures

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

Transaction Metadata & Performance Improvements

Compatible with [email protected] and [email protected].

New Features

• Added support for embedded transaction metadata for standard payments #2110 #2108 #2103 #2096 #2091 #2090 #2089 #2087 #2079 #2131
• Setup nightly restoration benchmarks syncing with mainnet and testnet #1695 #2122 #2045

Improvements

• Increased maximum address pool gap allowed for sequential wallets to 100 000 #2050 #2121
• Extended nightly restoration benchmarks to simulate large wallets #2081 #2084
• Improved performance of various API endpoints, including
  • fee estimation
  • random address import
  • address listing
  • transaction creation
    #2116 #2112 #2014 #2033 #2030 #2028 #2105
• Pruned retired stake pools from database after a safe period #2057 #2053 #2048 #2047 #2038 #2024
• Improved docker image network compatibility with host machine #1999
• Revised pool id to be shown and parsed as bech32 strings with pool as a prefix #2093 #2106 #2055
• Removed cardano-wallet-byron package (now fully absorbed by cardano-wallet) #2012

Resolved Issues

• Fee estimation on Shelley wallet takes very long when: transaction's amount > available balance #1905
• Listing transaction when node is still in the Byron era may fail with an Internal Server Error #1971
• Fixed fee balancing algorithm not respecting the transaction max size #2117
• Fixed underflow in fee estimation in the presence of withdrawal #2086 #2010
• Fixed API latency benchmarks, broken since the Shelley hard-fork #2046
• Fixed account balance fetching freezing the server for a short while #2034
• Included support for TLS-1.3 in the pool metadata HTTP client #2003
• Removed now broken / obsolete haddock link in README #2102
• Fixed blocking IO in integration tests on Windows #2101
• Fixed non cross-platform compatible functions used in integration tests #2095
• Returned a more descriptive error when listing stake pools with incomplete data #2094
• Returned a more descriptive error when listing transaction in the Byron era near the Shelley hard-fork #2059
• Fixed build issues with stack when building from Windows #2092 #2056 #2037
• Disabled RDRAND support causing issues with AMD processor #2115

Known Issues

• [SEVERITY:LOW] nix-build -A cardano-wallet fails on macOS Big Sur #2070
• [SEVERITY:LOW] Required wallet DB fields do not get persistently added #1743
• [SEVERITY:LOW] cardano-wallet address command group has commands which are not supported for shelley wallets #1733
• [SEVERITY:LOW] bech32, cardano-{address,tx} release executables don't work on macOS without nix #2134
• [SEVERITY:MEDIUM] Protocol parameters in checkpoint are never updated #2035
• [SEVERITY:MEDIUM] The reported value of pool saturation is incorrect #1980
• [SEVERITY:MEDIUM] Stake pool DB worker doesn't save sync progress in Byron #1963
• [SEVERITY:MEDIUM] Balance temporarily increases when spending rewards #1955

Known Limitations

Workaround for #2134:

On MacOS cardano-address, cardano-tx and bech32 executables that are present in the bundle will work only if you have Nix installed with *.dylib libraries they require (*.dylibs are also present inside the bundle). As a workaround one can redirect paths to dylibs manually:

1. List paths to dynamic libs for executable:

otool -L ./cardano-address
./cardano-address:
	/nix/store/f573hx6rga70hx5xjqrvqa58jkdxdl91-Libsystem-osx-10.12.6/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1226.10.1)
	/nix/store/p95rm5rlv4fmi0k81nr0l29ax57dw1r0-zlib-1.2.11/lib/libz.dylib (compatibility version 1.0.0, current version 1.2.11)
	/nix/store/m3yqw7xcmhvd0cmm3jh3b469kxf3yhfp-libiconv-osx-10.12.6/lib/libiconv.dylib (compatibility version 7.0.0, current version 7.0.0)
	/nix/store/hrmqighslwzk32rmz00k1lw5k53f5jr3-gmp-6.2.0/lib/libgmp.10.dylib (compatibility version 15.0.0, current version 15.0.0)
	/nix/store/w1v69v7w418nvsc3rxndp4cq59110bzj-libffi-3.3/lib/libffi.7.dylib (compatibility version 9.0.0, current version 9.0.0)

2. For each *.dylib path do:

install_name_tool -change /nix/store/path/*.dylib @executable_path/*.dylib cardano-address

Documentation

Cardano (cardano-node)	ITN (Jörmungandr)
API Documentation	API Documentation
CLI Manual	CLI Manual
Docker Manual	Docker Manual

Installation Instructions

Cardano (cardano-node)

1. Install [email protected].

2. Download the provided cardano-wallet for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

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

Docker

Pull from DockerHub and verify the version matches 2020.9.11.

$ docker pull inputoutput/cardano-wallet:2020.9.11-shelley
$ docker run --rm inputoutput/cardano-wallet:2020.9.11-shelley version

ITN (jormungandr)

1. Install [email protected].

2. Download the provided cardano-wallet-jormungandr for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

3. (optional) Install the bash/zsh auto-completion script according to the jormungandr cli manual

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

Docker

Pull from DockerHub and verify the version matches 2020.9.11

$ docker pull inputoutput/cardano-wallet:2020.9.11-jormungandr
$ docker run --rm inputoutput/cardano-wallet:2020.9.11-jormungandr version

Signatures

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

ITN Reward Redemptions on Cardano mainnet

Compatible with [email protected] and [email protected].

New Features

• Support for rewards redemption from another wallet #1967
• Support for external stake pool metadata registry server (via --smash-url) #1884

Improvements

• Added user advice to UnableToDetermineCurrentEpoch error #1992
• Reduce needless queries when constructing the list of stake pools #1982
• Better command-line help for --mainnet serve option #1978

Resolved Issues

• Revised stake pool metadata fetching prioritization (newly registered pools are now fetched first) #1995
• Catch request parsing errors instead of throwing in the main thread #1995

Known Issues

• #1743 [MINOR] Required wallet DB fields do not get persistently added
• #1905 [MINOR] Fee estimation on shelley wallet when takes very long when: transaction's amount > available balance
• #1963 [MINOR] Stake pool DB worker doesn't save sync progress in Byron
• #1971 [MINOR] Listing transaction when node is still in the Byron era may fail with an Internal Server Error
• #1980 [MINOR] The reported value of pool saturation is incorrect

Documentation

Cardano (cardano-node)	ITN (Jörmungandr)
API Documentation	API Documentation
CLI Manual	CLI Manual
Docker Manual	Docker Manual

Installation Instructions

Cardano (cardano-node)

1. Install [email protected].

2. Download the provided cardano-wallet-shelley for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

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

Docker

Pull from DockerHub and verify the version matches 2020.8.3.

$ docker pull inputoutput/cardano-wallet:2020.8.3-shelley
$ docker run --rm inputoutput/cardano-wallet:2020.8.3-shelley version

ITN (jormungandr)

1. Install [email protected].

2. Download the provided cardano-wallet-jormungandr for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

3. (optional) Install the bash/zsh auto-completion script according to the jormungandr cli manual

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

Docker

Pull from DockerHub and verify the version matches 2020.8.3

$ docker pull inputoutput/cardano-wallet:2020.8.3-jormungandr
$ docker run --rm inputoutput/cardano-wallet:2020.8.3-jormungandr version

Signatures

Name	Role	Approval
Matthias Benkort @KtorZ	Technical Team Lead	✔️
Matthias Benkort @KtorZ	QA Replacement	✔️
Tatyana Valkevych @tatyanavych	Release Manager	✔️

Shelley Hard-Fork

Compatible with [email protected] and [email protected].

New Features

• Support for the hard-fork combinator #1875 #1887 #1890 #1898 #1899 #1901 #1909 #1922 #1924 #1931
• Support for transaction withdrawals in Shelley (new query parameter ?withdrawReward) #1865 #1892
• Support for a minimum UTxO threshold in Shelley #1894 #1916 #1927 #1947
• Support of bootstrap Byron witnesses in Shelley Transactions #1849
• Support for the Shelley hard-fork countdown #1932
• Processing of stake pool retirement certificates #1847 #1913 #1945 #1957 #1968
• Enabled latency benchmark for the byron;shelley server #1829 #1845

Improvements

• Added more debug-level logs in the chain-sync client #1826
• Configured log rotation in docker-compose #1797
• Reduce verbosity of the pools engine (in particular, when fetching non-myopic member rewards) #1864
• docker: Make latest point to latest shelley image #1938

Resolved Issues

• #1708 [MAJOR] cardano-wallet-shelley workers crash
• #1713 [MAJOR] Performance issues /v2/byron-wallets/{walletId}/addresses API
• #1733 [MINOR] cardano-wallet-shelley address CLI has commands which are not supported for Shelley wallets
• #1823 [MAJOR] Trying to join pool returns 500 when there's no next delegation
• #1833 [MAJOR] There are un-joinable pools on shelley_testnet

Known Issues

• #1572 [MINOR] Recovery from chain-following exceptions may cause node to crash
• #1743 [MINOR] Required wallet DB fields do not get persistently added
• #1867 [MINOR] Wallet doesn't show meta data re-registered (in case of changing metadata url without changing metadata hash)
• #1905 [MINOR] Fee estimation on shelley wallet when takes very long when: transaction's amount > available balance
• #1963 [MINOR] Stake pool DB worker doesn't save sync progress in Byron

---

⚠️ IMPORTANT ⚠️

While in the Byron era, cardano-wallet will be unable to emit transactions. Once the hard-fork has occurred, the entire interface will become fully functioning.

---

Documentation

Link	Audience
API Documentation	Users of the Cardano Wallet API
CLI Manual / CLI Manual (ITN)	Users of the Cardano Wallet API
Docker Manual / Docker Manual (ITN)	Users of the Cardano Wallet API

Installation Instructions

Cardano (cardano-node)

1. Install [email protected].

2. Download the provided cardano-wallet for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

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

Docker

Pull from DockerHub and verify the version matches 2020.7.28.

$ docker pull inputoutput/cardano-wallet:2020.7.28-shelley
$ docker run --rm inputoutput/cardano-wallet:2020.7.28-shelley version

ITN (jormungandr)

1. Install [email protected].

2. Download the provided cardano-wallet-jormungandr for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows.

3. (optional) Install the bash/zsh auto-completion script according to the jormungandr cli manual

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

Docker

Pull from DockerHub and verify the version matches 2020.7.28

$ docker pull inputoutput/cardano-wallet:2020.7.28-jormungandr
$ docker run --rm inputoutput/cardano-wallet:2020.7.28-jormungandr version

Additional notes

• On macOS: Make sure all *.dylib files are in the same directory as cardano-wallet binary.

Signatures

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

Shelley MVP

Compatible with [email protected] and [email protected].

New Features

• Remaining API endpoints in cardano-wallet-shelley completed, which include delegation / undelegation support, and stake pools listing with metadata support #1722 #1738 #1744 #1747 #1752 #1753 #1763 #1765 #1769 #1775 #1776 #1783 #1800 #1801 #1806 #1807 #1810 . Note the following details:

  • ⚠️ The stake pool resource is different from cardano-wallet-itn, both models are documented in the API documentation under different tabs. Key changes are summarized in the table below:

    jörmungandr (itn)	cardano-node (shelley)
    apparent_performance	removed
    metadata.pledge_address	replaced by pledge
    desirability	replaced by metrics.non_myopic_member_rewards
    saturation	replaced by metrics.saturation
    metrics.controlled_stake	replaced by metrics.relative_stake
    metadata.owner	removed

  • ⚠️ cost, margin, pledge and metadata are fetched asynchronously and may therefore be null temporarily. Although, once set, they should remain set

  • ⚠️ Stake pools are no longer ordered by desirability, but are ordered by non-myopic member rewards which require an indented delegated stake to be provided as a query parameter

  • ⚠️ Metadata are no longer tight to the owner, but are tight to the stake pool itself. Yet, if two stake pools register the same metadata, it is still possible to find duplicates

• Support for submission of already signed and serialized Shelley transactions #1766

• Support for bech32 encoding for Shelley addresses. The server will however still accept addresses encoded as base16 to keep compatibility with cardano-cli #1746

• Support for fetching transaction (both Byron & Shelley) by id #1795 #1804

• Support of recovery phrases of various lengths for Icarus and random Byron wallets #1809

• Addition of the decentralization level (a.k.a d-parameter) alongside other protocol parameters #1735 #1736 #1739

• Addition of the desired number of pools (a.k.a k-parameter) alongside other protocol parameters #1827 #1848

• Support for spending rewards as part of a payment transaction. The rewards will be converted as UTxO and used to pay for some of the fees. Rewards are consumed only when deemed worthy (adding them does not cost more than their value), and by explicit demand using a query flag #1843

Improvements

• Extensive fully automated integration tests for cardano-node in Shelley mode. We've developed a framework for running a local cluster of node made of 3 stake pools, 1 BFT leader and one passive node, all fully connected and running a private blockchain at will. The cluster uses a genesis file with pre-registered funds attached to HD wallets which can be restored using their recovery phrase to be used to write various test scenarios #1729 #1731 #1732 #1734 #1748 #1754 #1772 #1790

• More code re-use from cardano-addresses and in particular the command-line declarations for keys and recovery phrase manipulation. #1780. As a consequence, there are breaking changes in the command-line (see CLI breaking changes)

• Show latest value of protocol parameters instead of their value from genesis #1760

• Small API documentation reorganization to group endpoints by verbs #1802

• Faster fee estimation for Shelley transactions #1834

CLI breaking changes

• ⚠️ The mnemonic command has been renamed to recovery-phrase
• ⚠️ The key root command has been renamed to key from-recovery-phrase
• ⚠️ The wallet create from-mnemonic command has been renamed to wallet create from-recovery-phrase

Known Issues

• #1572 Recovery from chain-following exceptions may cause node to crash
• #1708 cardano-wallet-shelley workers crash
• #1713 Performance issues /v2/byron-wallets/{walletId}/addresses API
• #1733 cardano-wallet-shelley address CLI has import and create commands which are not supported for Shelley wallets
• #1743 Required wallet DB fields do not get persistently added
• #1823 Trying to join pool returns 500 when there's no next delegation
• #1833 There are un-joinable pools on shelley_testnet
• #1867 Wallet doesn't show meta data re-registered (in case of changing metadata url without changing metadata hash)

Documentation

Link	Audience
API Documentation	Users of the Cardano Wallet API
CLI Manual: Jörmungandr / cardano-node	Users of the Cardano Wallet API
Docker Manual	Users of the Cardano Wallet API

Supported Operating Systems

• Linux 64 bit
• MacOS 64 bit
• Windows 64 bit

Installation Instructions

Shelley testnet (cardano-node)

1. Install [email protected]

2. Download the provided cardano-wallet-shelley for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows

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

Docker

Pull from DockerHub and verify the version matches 2020.7.6:

$ docker pull inputoutput/cardano-wallet:2020.7.6-shelley
$ docker run --rm inputoutput/cardano-wallet:2020.7.6-shelley version

ITN (jormungandr)

1. Install [email protected]

2. Download the provided cardano-wallet-jormungandr for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows

3. (optional) Install the bash/zsh auto-completion script according to the jormungandr cli manual

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

Docker

Pull from DockerHub and verify the version matches 2020.7.6:

$ docker pull inputoutput/cardano-wallet:2020.7.6-jormungandr
$ docker run --rm inputoutput/cardano-wallet:2020.7.6-jormungandr version

Byron (cardano-node)

1. Install [email protected]

2. Download the provided cardano-wallet-byron for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows

3. (optional) Install the bash/zsh auto-completion script according to the byron cli manual

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

Docker

Pull from DockerHub and verify the version matches 2020.7.6:

$ docker pull inputoutput/cardano-wallet:2020.7.6-byron
$ docker run --rm inputoutput/cardano-wallet:2020.7.6-byron version

Additional notes

• On macOS: Make sure all *.dylib files are in the same directory as cardano-wallet binary

Signatures

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

Basic Shelley Testnet Support

Compatible with [email protected] and [email protected].

New Features

• New cardano-wallet-shelley executable targeting the first Shelley-only testnet that contains wallet, address and transaction support #1626 #1669 #1673 #1677 (Delegation features will be added in a further release)
• Live reporting of the decentralization parameter d for the mainnet Byron-to-Shelley transition #1725
• Support for restoring sequential Byron wallets from account public keys (previously only supported for Shelley) #1721
• New migration endpoints which support migrating funds from any wallet to any set of addresses. Previously migration only allowed migration from a Byron wallet to a known new wallet #1664, #1645, #1678, #1687, #1684

Improvements

• Up to 40% faster wallet restoration using pipelined chain sync #1615 #1665
• Reduced randomness when estimating transaction fees from running multiple selections #1679 #1653
• Usability and documentation improvements
  • Exemplary docker-compose.yaml for cardano-wallet and cardano-node #1634
  • API and CLI documentation improvements
    • Clarified the description of getNetworkParameters in the API and CLI. #1698
  • Code and Haddock documentation improvements #1728 #1715
  • Reduced / adjusted logging for NetworkLayer and NTP client #1630 #1636
  • Better rendering of bech32 error messages in key derivation CLI #1625 #1654

Removed

• #1694 Breaking ⚠️ Removed epochId argument from getNetworkParameters.

Resolved Issues

• #1701 Wallet "passphrase" info gets lost after updating cardano-wallet (#1704, #1717)
• #1647 cardano-wallet-jormungandr: Blockchain tip not set in REST context (#1681)
• #1670 Different behavior regarding resolved inputs when listing transactions with and without query parameters (#1685, #1696, #1697)
• #1683 Incorrectly documented HTTP response code for fee-estimation (should be 202 instead of 200)
• #1659 Race condition between byron addresses creation and wallet restoration
• #1660 The latest docker tag is now available as latest, instead of separate tags for each revisions, to avoid cluttering
• #1638 Modifed docker-compose.yml example so it is possible to run mainnet and testnet interchangeably

Known issues

• #1733 cardano-wallet-shelley address CLI has import and create commands which are not supported for Shelley wallets
• #1708 cardano-wallet-shelley workers crash
• #1572 Recovery from chain-following exceptions may cause node to crash

Documentation

Link	Audience
API Documentation	Users of the Cardano Wallet API
CLI Manual: ITN / Byron	Users of the Cardano Wallet API
Docker Manual	Users of the Cardano Wallet API

Supported Operating Systems

• Windows 64 bit
• Linux 64 bit
• MacOS 64 bit

Installation Instructions

Shelley testnet (cardano-node)

1. Install [email protected]

2. Download the provided cardano-wallet-shelley for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows

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

Docker

Pull from DockerHub and verify the version matches 2020.6.5:

$ docker pull inputoutput/cardano-wallet:2020.6.5-shelley
$ docker run --rm inputoutput/cardano-wallet:2020.6.5-shelley version

ITN (jormungandr)

1. Install [email protected]

2. Download the provided cardano-wallet-jormungandr for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows

3. (optional) Install the bash/zsh auto-completion script according to the jormungandr cli manual

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

Docker

Pull from DockerHub and verify the version matches 2020.6.5:

$ docker pull inputoutput/cardano-wallet:2020.6.5-jormungandr
$ docker run --rm inputoutput/cardano-wallet:2020.6.5-jormungandr version

Byron (cardano-node)

1. Install [email protected]

2. Download the provided cardano-wallet-byron for your platform, and uncompress it in a directory that is on your $PATH, e.g. /usr/local/bin. Or %PATH% on Windows

3. (optional) Install the bash/zsh auto-completion script according to the byron cli manual

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

Docker

Pull from DockerHub and verify the version matches 2020.6.5:

$ docker pull inputoutput/cardano-wallet:2020.6.5-byron
$ docker run --rm inputoutput/cardano-wallet:2020.6.5-byron version

Additional notes

• On macOS: Make sure all *.dylib files are in the same directory as cardano-wallet binary

Troubleshooting

cardano-wallet: error while loading shared libraries: libcrypto.so.1.0.0: cannot open shared object file: No such file or directory

libcrypto 1.0.0 is no longer shipped with RHEL for a while (since ver. 6) and
SuSE. On these distributions, it is impossible to install it using native
package manager (e.g. yum).

One possible work-around is to create an artificial symbolic link from a newer version of libcrypto:

sudo ln -s /usr/lib64/libcrypto.so.1.1.1 /usr/lib64/libcrypto.so.1.0.0

Alternatively, one may also try using the docker image instead.

Signatures

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