Blog > 2018

Backwards-incompatible changes in Cardano 1.4 Wallet API

Matthias Benkort and Jacob Mitchell cover what's new

18 December 2018 Matthias Benkort 4 mins read

Simplicity and Michelson - Input Output

Backwards-incompatible changes in Cardano 1.4 Wallet API

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, Creative Commons Mike Beeple

Launching Plutus and Marlowe at the inaugural PlutusFest

IOHK’s new smart contract tools for developers and financiers

17 December 2018 Amy Reeve 3 mins read

Launching Plutus and Marlowe at the inaugural PlutusFest - Input Output

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.

Marlowe: financial contracts on blockchain

11 December 2018 Prof Simon Thompson 4 mins read

Marlowe: financial contracts on blockchain

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.

Smart contracts language for Cardano launches at PlutusFest

Plutus Platform is developed by a world-leading team

11 December 2018 Prof Philip Wadler 4 mins read

Smart contracts language for Cardano launches at PlutusFest

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.

Programming a crowdfunder with Solidity and Javascript for Ethereum

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.

Programming a crowdfuncter with Plutus Platform for Cardano

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 Playground, an online emulator for Plutus Platform

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!

Preventing Sybil attacks

29 October 2018 Lars Brünjes 8 mins read

Preventing Sybil attacks

Building on last week’s post by Professor Aggelos Kiayias, IOHK’s chief scientist, I want to use this post to discuss another choice we made when designing Cardano’s reward mechanism. The mechanism is designed to give an incentive to stakeholders to ‘do the right thing’ and participate in the protocol in a way that ensures its smooth, efficient and secure operation. As was explained last week, to ensure fairness and decentralization, the rewards mechanism follows three principles:

  • Total rewards for a stake pool should be proportional to the size of the pool until the pool reaches saturation.
  • Rewards inside a pool should be proportional to a pool member’s stake.
  • Pool operators should get higher rewards for their efforts.

One necessary modification deals with pool performance. If a pool operator neglects his ‘duties’ and does not create the blocks he is supposed to create, the pool rewards will decrease accordingly.

Take the example of Alice and Bob who run pools of equal sizes. They are both elected as slot leaders with 100 slots each. Alice dutifully creates all 100 blocks in the 100 slots she leads, whereas Bob misses 20 slots and only creates 80 blocks. In this case, Alice’s pool will get full rewards, whereas Bob’s pool will get less. How much less exactly is controlled by a parameter.

The challenge

In this post, I want to concentrate on another potential challenge to the Cardano principles and explain how we decided to overcome it. The challenge was mentioned at the end of last week’s post: How do we prevent one person from creating dozens or even hundreds of small pools?

Note that for very large stakeholders it is perfectly legitimate to split their stake into several pools to get a fair share of the rewards.

An example of a Sybil attack

Let’s assume that we are aiming for 100 pools and therefore cap rewards at 1%. Let us further assume that Alice holds a 3.6% stake. If Alice does not split her stake, she will only get 1% of total rewards. If, however, Alice splits her stake, putting 0.9% into four different pools, her reward from each pool will not be capped.

The challenge arises if a small but devious stakeholder is allowed to create a large number of pools (possibly under assumed identities). If he manages to attract people to these pools (for example by lying about his costs and promising high rewards to pool members), he might end up controlling a majority stake with very little personal stake in the system. How could this happen?

Let’s imagine that there are about 100 legitimate, honest pools. If we didn’t guard against it, a malicious player could relatively cheaply create 100, 200 or even 500 pools under false names and claim low operational costs and a low profit margin. Many honest stakeholders would then be tempted to stop delegating to one of the 100 honest pools and instead delegate their stake to one of themalicious pools, which might outnumber the honest pools. As a consequence, the operator of those malicious pools would be selected slot leader for a majority of blocks and so gain control over the blockchain, opening it up to all kinds of mischief and criminal activities, such as double-spending attacks! He would, of course, have to pay for the operation of hundreds of nodes, but that cost pales in comparison with the cost of acquiring a majority stake by buying the majority of all the Ada in existence, which would be in the range of hundreds of millions to billions of dollars.

This would be disastrous because the security of a proof-of-stake system like Cardano relies on the idea that people with a lot of influence over the system should hold a lot of stake and therefore have every reason to help the system run smoothly.

Our solution

This type of attack, where the attacker assumes many identities, is called a Sybil attack, named after the 1973 novel Sybil by Flora Rheta Schreiber about a woman suffering from multiple personality disorder.

How can we prevent Sybil attacks?

One idea might be to make pool registration very expensive. But to prevent attacks, such fees would need to be extremely high and would prevent honest people from creating legitimate pools. Such a hurdle would be bad for decentralization; we want to encourage members of our community to start their own pools and not hinder their entry! There does have to be a modest fee for the simple reason that each registration certificate has to be stored on the blockchain and will consume resources, which have to be paid for.

Our game theoretical analysis led us to a different solution, one that won’t bar ‘small’ stakeholders from starting their own pools by burdening them with prohibitively high fees and a high financial risk.

When registering a pool, the pool operator can decide to ‘pledge’ some of his personal stake to the pool. Pledging more will slightly increase the potential rewards of his pool.

This means that pools whose operators have pledged a lot of stake will be a little bit more attractive. So, if an attacker wants to create dozens of pools, he will have to split his personal stake into many parts, making all of his many pools less attractive, thereby causing people to delegate to pools run by honest stakeholders instead.

In other words, an attacker who creates a large number of pools will have to spread himself too thinly. He can’t make all of his many pools attractive, because he has to split his stake into too many parts. Honest pool operators will bundle all their personal stake into their one pool, thus having a much better chance of attracting members.

The degree of influence a pool operator’s pledged stake has on pool rewards can be fine-tuned by a configurable parameter. Being a bunch of mathematicians with little imagination, we called this parameter ‘a0’. (A colleague suggested the Greek letter phi because it sounds like part of the nasty giant’s chant in Jack and the Beanstalk – ‘Fee-fo-fi-fum’ – and we’re trying to ward off harmful stake pool giants, but we’d be grateful to any member of the community who can come up with a good name!).

Setting a0 to zero would mean: ‘Pool rewards do not depend on the operator’s pledged stake.’ Picking a high value for a0 would result in a strong advantage for pool operators who pledge a lot of stake to their pools.

We have a classical trade-off here, between fairness and an even playing field on the one hand (a0 = 0) and security and Sybil-attack protection on the other hand (a0 is large).

To demonstrate the effect of a0, let’s look at the three graphs in Figure 1.

Figure 1. How a pool operator’s pledged stake affects pool rewards.

In the graphs, we are aiming for ten pools, so rewards will be capped at 10%. The size of the pool stake is plotted on the horizontal axis and the vertical axis shows pool rewards. Each graph depicts three hypothetical pools, where the operators have pledged 0%, 5% and 8% respectively to their pools (the pledged amount is called s in the graphs).

The first graph uses a0 = 0, so the pledged stake has no influence on pool rewards, and the three pools behave in the same way: rewards keep climbing as the pool size grows until they are capped when the pool controls 10% of the stake.

In the second graph, we see the effect of a0 = 0.1. The three pools are still similar, especially for small sizes, but they are capped at slightly different values. Pools with more pledged stake enjoy slightly higher rewards when they grow bigger.

Finally, the third graph shows the effect of a0 = 0.5. It is similar to the second graph, but the differences between the three pools are more pronounced. We still have to choose a “good” value for a0. This choice will depend on quantities such as expected operational pool costs, total rewards and – most importantly – the desired level of security.

We will want to keep a0 as small as possible, while still guaranteeing high levels of security against Sybil attacks.

In any case, it is important to keep in mind that the introduction of a0 does not prevent ‘small’ stakeholders from running successful pools because somebody with a great idea can always reach out to the community, convince others and invite them to work together and pool resources to pledge to the pool. In the end, running a solid, reliable pool and working closely with the community will be more important than just owning a lot of stake.

We have also started thinking about replacing the dependency of rewards on the pool leader’s stake with a reputation system. This would allow people with little stake to make their pools more attractive by running their pools reliably and efficiently over a long period of time. This won’t be implemented in the first iteration, but is on the table for future versions of Cardano.

You might also like to read the IOHK technical report ‘Design Specification for Delegation and Incentives in Cardano’ for a broader, more detailed description of the system.

On Monday, 5 November, IOHK will hold an AMA (Ask Me Anything) on staking in Cardano, where anyone will have the opportunity to put questions to the IOHK team. Details of the AMA will be announced soon.

Artwork, Creative Commons Mike Beeple