Documentations related to state channels

Hi,

Can some one please point out documentation/whitepaper/demo-project related to state channels?

Thanks!

1 Like

Hey @vishwas_hypermine

@dimitar.chain can probably direct you to the latest documentation.

Thank you,
Albena

2 Likes

@vishwas_hypermine so channels have different levels of abstraction. There is a different documentation for each one of them.

State Channels provide a means of taking all the updates between two participants off-chain. There are some on-chain transactions that are expected - for example opening a State Channel requires it to be opened on-chain so tokens are locked in it. Later on participants might want to take some tokens out, deposit more or even close the channel - those are on-chain transactions as well. Meanwhile there would be soft-real time updates that are off-chain. All of this requires a protocol that is independent of the on-chain one. Other projects call this a layer2 architecture but in Aeternity Channels primitives are part of the on-chain protocol so it is L1. Yet the off-chain communication is completely separeted by the on-chain one in a protocol of itself. You can read about it here. This is already implemented in the State Channel’s Finite State Machine or simply - the FSM. It not only implements the encrypted off-chain protocol but also persists state and handles connections. It comes with the node, batteries included. The link above is intended both for people that want to gain general understanding how State Channels work under the hood but also for teams that want to build compatible implementations of the FSM. If you’re new to AE State Channels, I strongly recomend reading it as well with the other documents in the directory.

If you don’t want to implement a FSM of your own, you can use the one provided in the node itself. It provides a WebSocket connection to clients, while the two FSM talk to each other through an encrypted noise connection. The architecture looks like this:

+---------+                   +---------+
|         |                   |         |
| ClientA |                   | ClientB |
|         |                   |         |
+---+-----+                   +----+----+
    |                              |
    | WebSocket                    | WebSocket
    | connection                   | connection
    |                              |
    |                              |
+---+---+                     +----+--+
|       |                     |       |
| FSM A +---------------------+ FSM B |
|       |        enoise       |       |
+-------+      connection     +-------+

Where each client can also be a service - the other end really doesn’t know if it is talking to a person or a program. If you use the node-provided FSM, you only have to handle the WebSocket API. Its documentation can be found in the protocol as well:

  • a dry description of the API - this is just the API and corresponding events. This is intended for a quick lookup what a certain event looks like and what the expectations for the data are
  • intended API usage describes how API is to be used with a focus on flow. Let’s say you want to deposit some more tokens in the State Channel on-chain - this document describes who does what. It also takes note on important stuff and basically guides you through the API
  • we’ve modified the test SUITEs to export logs: those are the actual WebSocket messages sent and received by the two participants in the tests. Since tests intend to represent real-life usage scenarios, the examples could be helpful as well. You can find them here.

Regarding the whitepaper example - you can see its smart contract. It is being part of the FSM’s test SUITE so it works. You can see the description behind the logic here or if you prefer - in the generated PDF.

Regarding a demo projects - there had been some in the past but those were depricated and are not supported. As far as I know - none of them is working with recent SDK version. There is an on-going State Channel showcase project going on but it is not yet ready. The code is all public and out there but since not being ready - it might not be stable yet. It is intended to showcase a real-time interaction off-chain. For example at the moment I am writing the contract for it. Once it is ready, I will create a post for it, describing different approaches being used here and there. If you’re curious you can peek in the work in progress version of it here. Please don’t use it in a real-life scenarios as it might have bugs and this most likely is not the final version of it.

Possibly one wouldn’t like to implement all communication from scratch. That’s where SDKs come into play. I will let @nduchak.chain provide information for JS SDK and maybe either @aleksandar.chain or @Arthur to provide information for the Elixir SDK and channel’s service.

Hopefully this helps.

Regards,
Dimitar

4 Likes

Thank you @dimitar.chain for detailed descriptions of documentations. My intent is to build a demo application using payment channel (I am thinking to skip of smart contract part for now to simplify the process). The other objective of this exercise is to get hands on channels and its implementations. I am taking the use case of API payment as a use case. At high level something like this:
image

Will write about the use case in a separate post and provide the source code once its ready.

I prepared this diagram based on my understanding that there would be 2 things, one is off chain activity and 2nd is on-chain activities. In the above figure (1) and (3) are on-chain and (2) is off-chain activity. For on-chain I have to implement (or rather use) channel_create_tx, Channel_deposit_tx, Channel_withdraw_tx, Channel_snapshot_solo, channel_close_mutual, Channel_close_solo and Channel_settle functionalities by connecting to aeternity blockhain node. Of-chain activities, I have to manage at app level. Is my understanding correct?

2 Likes

I am not sure we are on the same page. From your post I understand you want to implement a protocol of your own. If that is the case, I would warn you that this could be quite a lot of work.

Especially if it is a demo, may I suggest you take a look at the FSM? All of (1), (2) and (3) are ready for you. The FSM will happily produce transations for you, it will update its state, it will send them to the other FSM which will validate them and pass them to its client (being either API Consumer or API Provider) to authenticate. It will monitor the chain for forks and will worn you if the other party tries cheating you. All of this is handled for you. You can of course implement it yourself and this is perfectly fine if you want to do so.

If you want to use the FSM though, this is what your example would look like:

+----------+                  +----------+
|          |                  |          |
|   API    |                  |   API    |
| Consumer |                  | Provider |
|          |                  |          |
+----+-----+                  +-----+----+
     |                              |
     | WebSocket                    | WebSocket
     | connection                   | connection
     |                              |
     |                              |
 +---+---+                     +----+--+
 |       |                     |       |
 | FSM A +---------------------+ FSM B |
 |       |        enoise       |       |
 +---+---+      connection     +---+---+
     |                             |
     |                             |
     |                             |
     |                             |
     |                             |
 +---+-----------------------------+---+
 |                                     |
 |             blockchain              |
 |                                     |
 |                                     |
 +-------------------------------------+

You get the API Consumer and the API Producer. They consume the WebSocket API. This is how they inform the FSM for their intentions. The FSM takes on from there and communicates those intentions with the other FSM. Both FSMs monitor the blockchain for transactions that relate to this particular state channel, keep the state, keep the enoise connection with the other participant. API Consumer and the API Producer don’t really care how the information propagates to the other FSM or the blockchain as the FSM handles this for them. They only have to implement handling of corresponding WebSocket events.

1 Like

Hey is it possible to avoid the websocket connections between the API consumer and FSM A or API provider and FSM B?
Like can

  • the API consumer can form the transaction, half signs it and then sends it to API provider over http,
  • the API provider can then signs the half signed transaction, hence making it full and update his FSM. and sends the http response with full signed tx.
  • upon receiving the response, the API consumer can then go ahead and updates his FSM

can this flow be possible?

From an on-chain protocol point of view - it doesn’t really matter how people build the transactions they provide to the blockchain, so not impossible but there is currently no support for it.

The FSM supports a WebSocket protocol but could be extended to use a plain HTTP one. This would come at a high price though: the WebSocket supports pushing of messages, so when the FSM detects a certain on-chain event - it notifies its client immediately via a corresponding message. The HTTP protocol you’re asking for would rather have to rely on polling to get those. The WebSocket also provides authentication and encryption of the messages sent and received, and this is something that should be handled in the HTTP protocol as well.

Again - not really hard to do but it requires some work. Eventually this could be beneficial for environments where we don’t expect a stable internet connection.

cc @uwigeroferlang.chain

1 Like

I think it would be a good thing to have since we can not assume stable internet connections anywhere.

Who can implement it and how much time would that take?

1 Like

Sorry I did not get this part, when does this required? like are you talking about the situation where, client A, initiates a channel_close request, which is an on-chain event, the client B has to get notified in order to mutually sign the transaction?

1 Like

@dimitar.chain @yani.chain

Guys I want to give some insight on what I am trying to achieve and why I am asking these questions.

So in my head (hypothesis), I am imagining a protocol for simple-micro payment over http. To prove my hypothesis, I will use pey-per-api-call usecase and for that I was planing to implement on Ae-Ternity payment channel. There is a paper on it, implemented on Bitcoin network. but it has its own complexities.

Why this protocol can be useful?

  1. Client do not need to provide any of his private information (credit card) to avail service from server
  2. One step solution for payment and resource consumption
  3. Paying resource per usage

Note: I am assuming, they both have channel established.

@vishwas_hypermine now I get what you want: you want to send arbitrary data that does not belong to the transaction in the first place. Although you could send HTTP requests to the server itself, may I suggest you take a look at generic messages. They are a means to send a message directly from one participant to the other and they could contain anything. So inside the channel you can ask the server for a resource and it can provide it to you simply using the functionality that is already there.

Generic messages are intended to to exactly that: they provide the means for applications to build their own protocols.

1 Like

I will create a separate thread to discuss this.

Okay I havent understood completely how a generic message is going to be useful in mycase, but let me take a deeper look on the generic message.
But one question though, what about the actual payment for resource, like I assume generic message is not meant to be used for payment (although on can specify “amount” in the message.info but then there would be problems like double spending and all right?)?

Thanks!

If you want to do it in a single step, you can also use meta information. Basically every tx can come with an additional piece of information, so you can do:

  1. Client send an off-chain transfer with the resource ID/URL. This includes the prices to be paid
  2. Server confirms (1) and sends back resource data as a generic message

Using simple payment channels, this is as secure and thrustless it gets. If you want to dispite situations like “server didn’t send the generic message, I want my tokens back”, you need to use contracts.

1 Like