Stateful client libraries

The client library team (Luca, Brord, Chris) has been putting together a design for an account module implementation for our client libraries - JS, Java, Go.

Please see the proposal document so you can comment directly. For general comments and questions on the design, please use the comments section here. The document links to 3 different .SVG files as they communicate the logic better, please refer to them - they can be opened in a browser.

Luca also built a PoC website and wallet integrating an implementation of the account module. This will help you understand the logic of the approach as well.


We’d like to get internal input on this before we present to the community and partners and start implementing a solution. There have been a couple iterations on this and we believe we’ve arrived on agreement on most (not all) of the design choices.

Some implementation details are omitted from this document.

So after giving the proposal a read, I don’t find the proposal in its current form very usable.
It’s lacking clear specification of the various methods so they can be ported across different languages.
Also lacks flows for how some of the methods should work. I’m not talking about the logical flow of e.g. the ‘donation SVG’, but about each of the methods used, their names, etc.
To end up with a maintainable system, the various implementations should mirror each other as much as possible. For that, hard method contracts are required. Code is not specification given that we want multiple implementations from the beginning. Essentially, we need to have this implemented on a whiteboard with logic blocks!?

For example, the Go impl is doing background threading work (should probably take Context parameters btw), but this kind of threading isn’t even discussed in the proposal.

After reading the proposal, why aren’t you tieing the deposit address to a MAM channel? That way, you don’t need hard timeouts because you could inform other listeners of when an old deposit address is no longer available and was switched to sth else?

P.S. Also regarding the Go account impl: I think the Account API (or at least the builder) is mixing together a lot of different concerns; the various background services should probably be split into standalone packages?

I agree to @anon45419615 points.

The motivation of the proposal is a good one. So, we should definitely think about solutions for it.
I see two approaches for it

  • Libraries with Caching Layer. Let’s call them wallets.
  • Embedded shareded full-node


A wallet is another layer on top of the client libraries. The client libraries only gives the user the ability to create and attach transactions. The layer which wraps the library can take care of funds etc. My instinct tells me that I would call this wallet. To simplify things, I would create an eventual consistent caching layer. Otherwise, it makes everything too complicated. You can block new transactions, until you synced the funds with a full-nodes.

Embedded shareded full-node

This solution might be in the direction of ICT. So, you have a sharded full-node (swarm node?) which keeps a partial state of the tangle. It also has neighbors, but not necessarily in a permanent matter.

The donation address problem is a completely different problem and I would address with another specification. The mentioned solution by @anon45419615 with binding the deposit address to a MAM channel sound like a good approach to me.
There might be also other solutions like this. You could also combine it with something like a DNS system. So, you have some kind of readable address. Might also be in interesting approach.

FYI: this is the actual specification after which the account package is being implemented:

A working implementation can be found under the account branch of iota.go:

@luca.moser Is this specification, or the direction, now final and the decision is made? I am asking, because the document is read-only and I cannot add a comment there.

I’ve updated the link, should be possible now to comment. We are implementing a first version according to this document and then see what works and what doesn’t.

1 Like

Hey @philipp.blum,
I agree that wallet is another layer on top of client libraries. However optimal solution should be abstracted, otherwise wallet devs will reinvent the wheel or produce vulnerable code. In any case they will be able to use the legacy (by then) prepareTransfers function to take care of funds themselves. But most likely they need something that adds value without cognitive overhead.

@anon45419615 I’ve been thinking about possible MAM integration and seems to be useful. Particularly it can be used as the means of address exchange. Then, depositor and recipient don’t have to worry about passing addresses around, they just need to “pair” once. This is important because many things could go wrong in address exchange causing address reuse.

If we use MAM to inform other listeners about when an address is no longer available, we’ll have to await their responses to make sure they are aware of our decision to spend the deposit address. It all stops working if one depositor halts. Therefore using a single address for multiple deposits locks funds, and removes ability to credit legitimate transfers.

Timeouts seek to address this problem, assuming synchronized clocks and reliable network. It’s apparent that timeout logic fails if, for example;

  1. Transaction doesn’t propagate to list of connected nodes. (could be public wifi failing)
  2. Coo goes down for maintenance.
  3. Transactions simply don’t reach Coo.

Recipient can’t distinguish which transactions are legit, without checking inclusion of sweep, and that would lead to halting when detecting unfunded transactions.

Physical time doesn’t have a place in a distributed system specification anyway, the specification should be given in terms of events observable within the system, according to Lamport ( That’s why timeouts & multi-use need to be removed from the proposal; they will lead to loss of funds, even if the developer uses them according to the spec.

I really feel like we are running around in circles as long as we don’t finally have reusable addresses. For me, all the approaches we are coming up with (also my own) are just hacks on top of a protocol which lacks a fundamental safety measure to do correct transaction settlement.

Whether you broadcast your address via MAM or you communicate the lifetime of your addresses, there’s always opportunity for funds to be sent to spent addresses. If I was a company considering to use IOTA for payments, that would certainly be a deal breaker.

By not having reusable addresses, it always boils down to the sender and receiver having to actively communicate with each other, in order to correctly exchange addresses. I dislike any approach in which the receiver must perform PoW to message the deposit address to potential depositors (or for that matter, that both parties must be online). Even if deposit addresses are communicated, it is still bad that subsequent deposit addresses will again need to be exchanged between the sender and receiver. Surely, this address exchange just eats up energy and I question whether this makes sense if we are building a technology for “IoT”. Let alone how non ergonomic it is to not be able to use the same address multiple times when you send money to your friends, banks etc.

I am fully self aware that messaging timeouts and the intentions on how you as a receiver are going to use the address are not 100% safe but they are surely much safer than the current approach where there’s no clear cookbook on how to do input selection, plain addresses being exchanged without knowing how long they are valid and relying on wereAddressesSpentFrom. Clearly, all we are doing with addresses regarding the account spec I wrote, is try to make an insecure payment protocol just a little more safe but it surely doesn’t fix the underlying protocol’s mistake.

I’d really love if we finally would come to a decision regarding implementing reusable addresses, as it would solve so many problems and make the protocol actually usable for payments.

1 Like

I totally agree. I think that should be something which is in the core of IOTA.
Not sure if that is a big deal breaker for IoT. For the Internet where end-user are involved: It is definitely a deal breaker. I am not sure for IoT, because you can ask another node for the address, when you want to send funds. While this is possible, it also doesn’t need to be completely secure. But I think that is one of the smaller issues we currently face on IoT. Due to ternary, IOTA is currently not usable on Microcontroller. Bundle with 3 transactions: ~ 8 seconds creation time. So, impossible to use it in application with real-time requirements. So basically every IoT use-case has some kind of real-time requirement.