State Channels JS library

It will be great having more state channels’ apps running on phones. Currently there is an example implementation of the off-chain protocol built in the node itself. This sadly requires a synced node and an opened connection to it. It might be worth the effort moving some of the functionality to the client’s side.

One big obstacle for this would be validating contracts off-chain. In order to do this, the client would need to be able to run the VM locally, which is not a trivial task. In my opinion this should not be a blocker for developing a librarary that does everything else, except contracts. That would mean builing a library that can talk to a few nodes in order to build a consesus for the state of the chain. It must be able to connect to the other participant and implement a huge portion of the off-chain protocol. It must be able to create and validate non-contract transactions in trustless manner - both on-chain and off-chain - and sign them. Once there is a solution for the contract’s executution, we can enrich this client library with it. At this point of time I am talking for a library that supports only payments, not contracts.

At the moment I am thinking it would be a great starting point having this runnable in a browser, so we need a JS library. As we already have the SDK, we might already have some of the pieces to build it. Later on this can be integrated in the Base Aepp.

So functionally speaking - what shall it do? I tried shortlist:

  • it must be able to build and check on-chain transactions: channel_create, channel_deposit, channel_withdrawal, channel_close_mutual, channel_snapshot, channel_close_solo, channel_slash and channel_settle. This seems to be covered by the JS SDK, for example - the channel_create can be seen here.
  • it must be able to build and check off-chain transactions - the channel_offchain transaction as well as a subset of the off-chain updates: transfer, deposit and withdrawal (note - no contract create and call). This is already handled in the SDK as well.
  • transactions must be authenticated and checked in a safe manner. This requires RLP encoding and decoding, building a signed_tx and etc. but all of this is already provided by the SDK. Since we are not doing contracts yet, no generalized accounts (yet).
  • it must be able to build and update off-chain trees. This is required for the trustless part: receiving an incoming off-chain transaction and a set of updates, the library must be able to check that adding it to the current state trees, the root of the newly produced trees will match the one in state_hash of the off-chain transaction. This might not be provided already by the SDK but there must be at least a decent MPTrees library
  • in order to be able to talk to another participant, it must be able to open a noise connection to another participant (probably to a responder). I am not sure how this will play in a browser environment
  • it must implement most of the off-chain protocol. I think the all messages must be handled, including the contract updates as those must be rejected at this point. This will be a decent chunk of work but it must be done anyway if we want to move parts of the FSM to the client itself
  • although a different approach could be taken, it would probably have to reimplement either parts of or the whole Finite State Machine in JS.
  • with regard of keeping the client safe at all time and being trustless, it must be able to build consesus for the on-chain state of the channel: if the client is helping Alice, she must be informed by her client library when Bob tries cheating on-chain (with providing some old state on-chain). This means that the client must ask a few different nodes for the channel’s state and build consesus upon their responses. This is also required for waiting a certain amount of confirmations for on-chain transactions (channel_create, channel_deposit and etc).

Note that all of the points above were just functionalities, each app can build a UX of their own :slight_smile:

So, what do you think for all of this? Did I miss something?


Fantastic! We’re looking for some JS pros who can support us here. If you feel you’d be the right one, please comment here and / or apply for a dev grant via


Hi @Dimitar.Ivanov,
I’m from kryptokrauts and @marc0olo showed me this discussion. I think a js library of off-chain state channels is important and will bring more use cases for State Channels. As I have a strong javascript background I might can support you in this topic.

May we can have a more in depth discussion about this:
Some things - as you already mentioned - are supported by the official aeternity javascript SDK.
One think I’m not sure about is the implementation of the noise protocol. As I understand you want to connect to a full aeternity node? I thought about a different approach. The communication itself can be moved to the application itself which is using the SDK. So the SDK would only be used to validate off-chain transactions between the parties. The communication can then be done by websocket or even NFC, Bluetooth or something simliar. What do you think about that?
You also may can provide some more detailed information about the Finite State Machine. E.g. a whitepaper or technical description about the functionality?

Looking forward to have further discussions on this.


Hi @icarus and welcome to the forum!

The idea is to connect to another FSM and this could be taken out of a full node. Yes, the idea is to move the communication, transaction execution and validation to the application itself. The communication itself could be done in various different ways, of course. Using NFC, QR Codes and etc. would heavily impact reactiveness of the system but it would also make it more resilient to network issues. Although great, network connectivity issues could open the door to many attack vectors so this intoduces a certain level of trustfulness I personally don’t like. This does not mean it is forbiden in any way: the protocol does not specify how the on-chain transactions are produced and it accepts them as long as they are valid.

You can see the state of the FSM in the wiki and you can read about the off-chain noise messages in the protocol itself.

Hi @Dimitar.Ivanov,
Thanks for the resources. I will have a closer look during the next days.
Again regarding the noise messages: is it right that we need to be able to understand noise messages but we do need to take care of the transport and this will be something each user of the library can decide?
I will also try to come up with some kind of a high level structure and feature list (based on the one you already posted)

1 Like

Hi @Dimitar.Ivanov,
I had a discussion with @marc0olo. We thought about the target platform for the library. We were thinking about the use cases and where the lib can be used. We thought that the focus would be mobile. What are your thoughts about this?

If the target platform is mobile i’m not sure if JavaScript is the right technology for the implementation.

May be you can share some of your ideas.

What other language would you prefer? I think Javascript makes the most sense, as you can make it work on all platforms.

@piwo that true but if the focus is mobile we would define that each user who wants to use the lib cannot write native apps, but needs to use some framework like Cordova, React Native it Nativescript. This is something we need to keep in mind.


Yes, you are right and we need to keep this in mind. But for the first implementation the goal should be the most general implementation we can find, then build native ones afterwards.

1 Like

If it is documented in a clean way, it should be easier for others to re-build it in other languages. Currently @noandrea is doing a great job with writing the Python SDK as some sort of reference for JS and Go. Everyone should always keep in mind that we want to onboard people along the way and be open for contributions.


Thanks for sharing your thoughts. May you can also provide your input on a further question I discussed with @marc0olo
Should the State Channel JS Lib be standalone or only work with the JavaScript SDK? In case we want to have it standalone we would need to duplicate some functions which are already available in the JS SDK like signing or opening channels. We could also define the State Channel Lib to “only” have a parser for noise messages (related to channels) and validation Tx using an implementation for the FSM?

@emin Thanks for your input. I totally agree, that we should provide good documentation during implementation so it can be converted to any target programming language.

1 Like