In this blog, wallet API lead Matthias Benkort explains backwards-incompatible Cardano wallet API changes that are coming in Cardano 1.4, and devOps lead Jacob Mitchell shows how to build a Cardano client with both the old V0 wallet API and the new V1 wallet API, instead of the default option providing only the new API. This blog post is mainly intended for current users of the Cardano wallet API; in particular, those who have already integrated with the beta release of the V1 API prior to Cardano 1.4.

The Cardano wallet API has its own versioning. As of Cardano 1.4 the previous V0 wallet API will become obsolete. All V0 API REST endpoints have been ported to V1 API, and the wallet rewrite gave the wallet team an opportunity to correct and improve the Cardano wallet semantics. As a result, there have been four breaking changes as described below. The V1 wallet API will become the default wallet API in Cardano 1.4.

1. The diagnostic structure of the NotEnoughMoney error has been changed to accommodate more cases.

2. The diagnostic structure of the WalletAlreadyExists error has been modified to provide the extra field walletId for the ID of the pre-existing wallet.

3. The behavior of /api/v1/addresses/{address} has been adjusted to more accurately reflect the semantics of ownership regarding addresses. The previous version of this endpoint failed with an HTTP error when the given address was unknown to the wallet. This was misleading, since an address that is unknown to the wallet could still belong to it. To reflect this, the V1 endpoint no longer fails, and instead when an address is not recognised it returns a new field isOurs, which indicates either that the address is ours, or that it is not recognised.

4. A DELETE request to /api/v1/wallets/{wallet} now correctly fails with a 404 HTTP response code if the wallet doesn't exist. Previously, it incorrectly responded with 204.

Regardless of whether the old or new data layer runs, the V1 API will have the changes described above. The first two changes are mostly intended so that developers can understand what's going on. If exchanges or other parties were using it to build a specific error message for their API or front end, then it may break.

The third change is more subtle and is actually a bug fix. The old behavior of the GET address endpoint was sending wrong information to nodes, so we have fixed it to improve its accuracy. In doing so, we had to introduce a new isOurs field and review what HTTP statuses were being sent - should exchanges have been relying on this for any business logic, they will need to update it.

The default installation of Cardano 1.4 will come with the V1 wallet API only.

Generally, exchanges and other integrators use stable releases to build a Cardano client using a shell script that launches a Cardano wallet against mainnet:

nix-build -A connectScripts.mainnet.wallet

In this case there is no roll back - Cardano wallet is upgraded to V1.

In order to have both V0 and V1 functionality developers should use useLegacyDataLayer in the custom-wallet-config.nix file as described in our documentation for exchanges. Caution! In this mode, despite making V1 endpoints available, the API won't utilize the newly developed data layer. As a consequence, developers may experience limitations known of the legacy data layer. This mode is therefore deprecated and we strongly recommend users to run nodes without it.

We have described backwards-incompatible changes coming with the wallet API in Cardano 1.4. Should anyone have trouble upgrading to 1.4, seek help through either an already established communication channel, or our support portal.

Artwork,

Cardano, the third-generation blockchain, is evolving. Cardano changes are planned as product increments within Cardano development phases, and are implemented and released as Cardano software. In this blog, product manager Darko Mijic, release manager Tatyana Valkevych and devOps lead Jacob Mitchell clarify how Cardano is versioned as a blockchain product and as software, and the correspondence between them.

Versioning Cardano as a product and as software

The Cardano product version reflects the evolution of Cardano as a sequence of new feature set deployments within a Cardano development phase, and uses the following versioning scheme of three numbers separated with dots:

development_phase.feature_set-1.refinement

where the refinement part can be omitted. For example, the Cardano version in production at the time of writing this article is 1.3.2, which means it is the second refinement of the fourth feature set for the first development phase.

Cardano is currently approaching the end of its first development phase called Byron.

Cardano development phases are:

1. Byron (Cardano 1.N) In the Byron phase a completely new cryptocurrency technology stack was designed and built, including entirely new code and the implementation of the first generation of Ouroboros, a provably secure proof of stake protocol (PoS) at its core. The settlement layer (Cardano SL) of Cardano was launched in a federated fashion with the system operated by IOHK, Cardano Foundation, and Emurgo. It enabled the launch of ada cryptocurrency and allowed users to transfer and trade ada.

2. Shelley (Cardano 2.N) The Shelley phase will transition the settlement layer of Cardano from a federated to a completely decentralized system which will allow all users to participate in the protocol, and get rewards for producing blocks by staking individually or within stake pools.

3. Goguen (Cardano 3.N) The Goguen phase will bring the second collection of protocols with the computation layer (Cardno CL) deployed as side-chains to Cardano with support for smart contracts.

4. Basho (Cardano 4.N) The Basho phase will be focused on performance, security, and scalability improvements. It will enable Cardano to scale to millions and billions of users.

5. Voltaire (Cardano 5.N) The final development phase, Voltaire, will add a treasury system and governance, enabling sustainability and self-sufficiency for Cardano.

So far we have released four main stable Byron releases, which are referred to as Cardano 1.0, Cardano 1.1, Cardano 1.2, and Cardano 1.3.

A new feature set implementation is delivered through a main stable release. In this case a release version may be represented by the first two numbers only: for example, Cardano 1.3 is the same as Cardano 1.3.0. Every main release may have subsequent refinement releases that include bug fixes and other improvements, but no new features. So far all main Cardano releases have been followed by refinement releases. It is important to stress that although a full Cardano product version consists of three numbers it does not follow semantic versioning.

The live Cardano product is represented by the latest software release, deployed on the Cardano mainnet. When a Cardano release is discussed on public channels it is the Cardano product version that is used by default. When we release a Cardano product increment we specify its software component versions in Release Notes on daedaluswallet.io and on GitHub [Daedalus releases, Cardano SL releases]. Below we clarify the correspondence between Cardano product and Cardano software versions.

At the time of writing Cardano consists of the following two software components:

• Cardano settlement layer (CSL) is a backend software component and its code lives in Cardano SL repository. It is the implementation of the Cardano node with all required components such as networking and also the implementation of Cardano wallet and its API. Cardano SL is deployed on Cardano core and relay blockchain nodes, and it is also shipped as a backend software component with Daedalus frontend.

• Daedalus software component (D) is a desktop application for personal computers running Windows, Mac and Linux and its code lives in Daedalus repository. It is a frontend for Cardano end users, and it ships with CLS component as its backend.

These software components are versioned according to the semantic versioning scheme most software follows, which consists of the three numbers major.minor.patch where:

• major is incremented when code changes are backwards incompatible

• minor is incremented when added functionality is backwards compatible

• patch is incremented when only bugs are fixed in a backwards compatible manner

The Cardano 1.3.0 main release consisted of Cardano SL 1.3.0 and Daedalus 0.11.0, or symbolically can be written as:

C_1.3.0 = CSL_1.3.0 + D_0.11.0

The Cardano 1.3.2 refinement release bundles Cardano SL 1.3.2 and Daedalus 0.11.2:

C_1.3.2 = CSL_1.3.2 + D_0.11.2

Cardano SL and Daedalus software releases are tagged with their version tags in the IOHK GitHub repository (see Cardano SL tags and Daedalus tags).

Cardano SL and Daedalus software release versions are also currently reflected in the Daedalus installer file name and in the download link on the https://daedaluswallet.io/download page, for example, the Cardano 1.3.2 Windows installer has the name

daedalus-0.11.2-cardano-sl-1.3.2-mainnet-windows-10311.exe

which includes Daedalus version, Cardano SL version, network, OS, and the build number.

While so far the Cardano product version and Cardano SL version have coincided, this is not the case for the Cardano 1.4 release due to backwards incompatible changes in the Cardano wallet API. The wallet API is part of Cardano SL, and therefore due to these incompatible changes the major number of Cardano SL version has been incremented, and this resulted in Cardano SL 2.0.0. So, Cardano 1.4 consists of Cardano SL 2.0.0 and Daedalus 0.12.0:

C_1.4.0 = CSL_2.0.0 + D_0.12.0

Conclusion

There is a distinction between the Cardano product version and versions of the Cardano software components. While this has always been the case, Cardano 1.4 is the first release where the distinction is evident, so we wanted to explain exactly how the versioning works.

Cardano 1.4 release is the fifth main release of the Byron phase and consists of the two software components Cardano SL 2.0.0 and Daedalus 0.12.0 versioned according to the semantic versioning. In the future, Cardano will include more components that will follow their own versioning schemes. For example, Cardano wallet is being rewritten as a standalone software component. The following phase in Cardano development Shelley will be versioned as Cardano 2.N.

Artwork,

Last week IOHK hosted the inaugural PlutusFest at the University of Edinburgh. Members of the IOHK team flew in from around the world, with interested academics, developers, financiers, and members of the press also in attendance.

Professor Philip Wadler reprises his role
as Lambda Man, PlutusFest style.

IOHK research fellow Philip Wadler opened the event - and his shirt, in traditional Lambda Man style - followed by a keynote from CEO and co-founder Charles Hoskinson, discussing the social nature of money, and why IOHK’s rigorous formal verification methods are even more important in the face of increasing decentralization.

Professor Aggelos Kiayias also spoke about the work of the Edinburgh Blockchain Technology Lab (BTL), and how they are working in tandem with IOHK to accelerate the transition of new ideas from academia to real-world applications. During 2017 - 2018, 21 academic papers have been published or co-authored by IOHK and BTL researchers, with a further 20 already submitted and awaiting peer review.

IOHK’s language architect Manuel Chakravarty introduced Plutus itself, a general-purpose Haskell-based functional programming language, designed for simplicity and longevity. It can be used to write both on- and off-chain applications, improving data transfer, code re-use, and developer experience when writing smart contracts, and minimizing the need for hard forks in the future.

Like all functional programming languages, Plutus ensures secure, high assurance code by its very nature. During the design process, it was decided that the core semantics of Plutus should be concise and elegant enough to fit on a napkin - and sure enough, all attendees of PlutusFest received a limited edition Plutus napkin, along with Plutus t-shirts (and optional capes).

Proof that the core semantics of Plutus fit on a (very fancy) napkin.

Professor Simon Thompson of the University of Kent also presented on IOHK’s Marlowe, a new user-focused domain-specific language designed to enable non-technical financiers to easily write on-chain smart contracts. The Marlowe research team have been working with business analysts to design smart contract templates, opening up the use of Cardano smart contracts directly to non-programmers in banks and other businesses, who will be able to automate financial transactions using cryptocurrency technology to save time and reduce costs.

Plutus and Marlowe are being launched now to allow interested developers and financiers to experiment ahead of the Cardano Shelley release in 2019. You can try out Plutus in the Plutus Playground, a lightweight, web-based emulator for writing and executing smart contracts in Plutus. For Marlowe, there is the Meadow emulator to try out as well, find out more here.

Other talks during the event included a discussion of formal verification from IOHK’s director of engineering Duncan Coutts, as well as a series of academic talks covering System F-Omega and using Agda to formalize Plutus metatheory.

The event also provided an opportunity for the IOHK team, who are based all around the world, to meet and work together in person. The Plutus and Marlowe teams spent some time discussing future development directions - and in some cases, meeting each other for the first time - while the broader IOHK team took the chance to talk strategy, planning, and goals for 2019.

From left, Grigore Rosu of Runtime Verification, Stewart Mackenzie of Fractalide, community member Robert Kornacki, and IOHK’s Lars Brünjes hard at work before PlutusFest.

If you’re interested in hearing the presentations from PlutusFest, subscribe to the IOHK YouTube channel where high quality, re-recorded versions of the talks will be posted soon. A more in-depth recap is also available on the Cardano forum.

The first computers were programmed in “machine code”. Each kind of system had a different code, and these codes were low-level and inexpressive: programs were long sequences of very simple instructions, incompressible to anyone who had not written them. Nowadays we are able to use higher-level languages like C, Java and Haskell to program systems. The same languages can be used on widely different machines, and the programs’ structures reflects what they do; on blockchain, their equivalents are languages like Solidity and Simplicity. These modern higher-level languages are general purpose – they can be used to solve all sorts of different problems – but the solutions they express are still programs, and they still require programming skills to use them effectively. In contrast, Marlowe is a domain-specific language (DSL) which is designed to be usable by someone who is expert in a particular field: in the case of Marlowe, financial contracts, rather than requiring programming skills to use it.

Using a DSL has many advantages beyond its use by non-programmers:

• We can ensure that certain sorts of bad programs cannot even be written by designing those possibilities out of the language, and by doing this we can aim to avoid some of the unanticipated exploits which have been a problem for existing blockchains.

• We can also more easily check that programs have the properties that we want: for example, in the case of a financial contract we might want to make sure that the contract can never fail to make a payment that it should.

• Because it is a DSL, we can build special-purpose tools to help people write programs in the language. In the case of Marlowe we can emulate how a contract will behave before it is run for real on the system; this helps us to make sure that the contract we have written is doing what it is intended to.

Marlowe is modelled on financial contract DSLs popularised in the last decade or so by academics and enterprises such as LexiFi, which provides contract software in the financial sector. In developing Marlowe we have adapted these languages to work on blockchain. Marlowe is implemented on the settlement layer (SL) of the Cardano blockchain, but could equally well be implemented on Ethereum/Solidity or other blockchain platforms; in this respect it is “platform agnostic” just like modern programming languages like Java and C++. The Meadow online emulator tool allows you to experiment with, develop and interact with Marlowe contracts in your web browser, without having to install any software for yourself.

What does a Marlowe contract look like? It is built by combining a small number of building blocks that describe making a payment, making an observation of something in the “real world”, waiting until a certain condition becomes true, and so on. Where we differ from earlier approaches is in how we make sure that the contract is followed. This means not only that the instructions of the contract are not disobeyed, but also that the participants don’t walk away early, leaving money locked up in the contract forever. We do this using two tools, commitments and timeouts: a commitment requires a participant to “put their money on the table”, and through timeouts we make sure that this commitment happens in a timely manner or remedial action is taken. Putting these constructs together we are able to incentivise participants to continue with the contract once they have committed to it.

We’re working on a full release of Marlowe for mid-2019, when it will be available on Cardano SL. From today, you're able to explore Marlowe for yourself using Meadow, and find out much more detail from our online paper. In the next six months we’ll be polishing the language design itself and developing a set of templates for popular financial instruments, as well as using formal logic tools to prove properties of Marlowe contracts, giving users the highest level of assurance that their contracts behave as intended.

Today IOHK releases Plutus Platform, a smart contracts language for the Cardano blockchain. You can try out Plutus online, with no need to download or install anything, via Plutus Playground. Plutus Platform is open source. You can find code, documentation, and sources here. IOHK is unique among cryptocurrency companies for its insistence on basing its development on peer-reviewed research, and is one of the few to support rapid and reliable development by using the functional language Haskell. Plutus Platform builds upon these strengths. It has been developed by a crack team of researchers and developers, led by Manuel Chakravarty – language architect at IOHK and who is well known to the Haskell community – and myself.

At the core of Plutus Platform is an intriguing research idea, cleverly spotted by Manuel. One tends to think of programming smart contracts in a single language, e.g., Solidity for Ethereum. For example, a standard example is a crowdfunding contract. The one here consists of 81 lines of Solidity, to run on-chain. But it also contains 149 lines of Javascript, to run off-chain.

Off-chain code provides a user interface to invoke the on-chain code. Further, because on-chain code is expensive, one wants to move as much computation off-chain as possible. The on-chain code should do the minimum required to guarantee secure functionality.

This distinction is one we’ve seen before. Web applications also run in two locations, on the server and on the client. The client provides a user interface to invoke code on the server. Further, because code on the server is expensive, one wants to move as much computation off the server as possible. The server should do the minimum required to guarantee secure functionality. The Links system, developed by me and my colleagues, was one of the first to address this problem. It allows developers to write a single source, from which is generated both code for the server (including SQL) and code for the client (in Javascript). A slew of similar systems followed.

Plutus Platform is designed similarly. It allows developers to write a single source, in Haskell, from which is generated both on-chain and off-chain code. An example appears in the diagram below. The on-chain code is written in Template Haskell, inside brackets [|| and ||], and is referred to as PlutusTx.

Manuel’s observation opens a new and promising field of research. We expect the on-chain vs off-chain and server vs client distinction is echoed elsewhere, for instance the user code vs kernel code distinction in operating systems appears similar. It may be possible to discover principles that apply across different areas, or to transpose ideas from one to another. For instance, flow types have been applied to web applications to guarantee that client code cannot violate the integrity of server code, and similar ideas might be applied to guarantee that off-chain code cannot violate the integrity of on-chain code. There is much to do!

Plutus Platform code can be run in three different ways. You can try out Plutus online, without the need to download or install anything, via Plutus Playground. It lets you edit and run code, and displays the state of the blockchain in graphic form. A couple of screenshots are below.

Plutus Platform is open source. You can find code, documentation, and sources here. These provide an emulator, a testing environment that lets you test without the hassle of running a testnet. And finally, of course, Plutus will execute in the next generation of Cardano. All three execute the same Plutus Platform code with the same results, save that you must use Cardano to actually spend ada. Please try it out and give us feedback!