Stateful Client Libraries: Part 2

Update: This library is deprecated with the Chrysalis network upgrade. The rust libraries will be more heavily maintained. Documentation can be found in our latest docs.

In the previous post, we highlighted some of the major changes in the client libraries, and how they simplify development on IOTA. In this post, we’ll look closer at the concept of Conditional Deposit Addresses (CDAs).

CDAs are special addresses that allow you to specify the conditions for which they stay usable. As long as the conditions you specify hold, the CDAs can be used for withdrawals and deposits.

The main use for CDAs is to avoid address reuse. When you request IOTAs from a party, you create a CDA that is active for a certain period of time and that can specify the exact amount of IOTAs. This way, you communicate intent to the sender, who then makes a judgment on whether to make a deposit. A simplified flow is:

You generate a CDA.
When creating the CDA, you specify conditions like the timeout— for how long the CDA stays valid and can be deposited to. Or an amount— how many iotas you expect the sender to deposit to the address.
You share the CDA with the depositor via a medium of your choice and serialized as an object of your choice, for example as a QR code, protocol buffer, or a magnet link.
The depositor either sends tokens to the address specified in the CDA, or requests a new CDA if for example, the CDA has already expired.

CDAs are simple, descriptive objects and you can serialize them into any format. This is what a CDA magnet link looks like, for example:

iota://GODULTSVAVRXBJFKTAEAJTULFKJUHIMKKVBCS9TJCNBWEVWFHAAVKVKLABMYTSK9EKWPMZJUVHAKGULLDAMABAGQIZ/?timeout_at=1554372484&expected_amount=1000

The libraries can parse the magnet link, and sending to a link that you receive can then be as simple as:

account.sendToCDA({magnetLink: magnetLink}).then().catch();

To showcase this concept, Luca Moser has built a web application that works as a web wallet (note — this runs on the devnet using test tokens):

Go to the Sigma Wallet website
Create an account.
Generate an address in the web wallet with the amount set to 1000.
Click the “COPY RAW ADDRESS” button and use it to get funds from the Devnet faucet. The funds should be available shortly, as you can see in the Balance section.
Generate a new address in the web wallet and click “COPY MAGNET LINK”.
You can paste this magnet link into the address field of the “Send” section of the wallet and send specific amounts to yourself.

If you specified the amount of IOTAs when generating the CDA, the IOTAs will become available in your balance as soon as they arrive. Otherwise, they will be blocked until the CDA expires, which is 30 minutes in this case.

Sending a transaction to a Conditional Deposit Address

One of the scenarios that are enabled by CDAs is the implementation of fixed-time donation addresses. You display a CDA on your website, for example as a QR code. And, every time the current CDA is about to expire, let’s say in the last 48 hours of the validity of the CDA, you generate a new one and display a new QR code. Leaving enough space for the already incoming transactions to safely come in and making sure all new donations are picked up by the new CDA.

You can see an example of this approach implemented in Go in this donation PoC repository.

Read more about the client libraries in our documentation. Or get the libraries from their respective repositories:

Thanks!