Refactor the clients to have proper names and layers

[lxfind]

First of all, similar to Ethereum, we should be able to talk to the Authorities in a stateless way, through CLI (similar to geth), REST or RPC. The API at this layer should be stateless (i.e. doesn't represent or own an account), and the CLI can be just called fastx.

Secondly, we then can have a ClientService, which encapsulates stateful APIs that a light client will typically need, to maintain a few accounts and persist objects.

Finally, we can then have a client_cli purely for the purpose of demoing the ClientService. Orthogonally, the ClientService can also expose REST APIs.

[lxfind]

The currently implementation is an artifact of FastPay, which binds Client to a specific account

[sblackshear]

An attempt at a diagram to clarify things a bit. Here, the box labeled "client" encompasses several components with distinct functionality. We refer to all of them as "client" today. The colored boxes attempt to give the distinct components descriptive names.

• Relayer: implements utility computation that is not appropriate to perform on an authority, but does not require persistent state. An example is collecting a quorum of signatures on an order to form a certficate. The relayer does not know how to construct an order, but if the client service hands it one, it will do the work required to create a certificate and forward both the certificate and effects back to the client service.

• Client service: the component that knows how to construct orders. It manages a nonempty set of addresses (i.e., the addresses that the wallet(s) it communicates with have private keys for). It knows the objects owned by each of these addresses at the current point in time, and may (optionally) store their historical values. It also knows every certificate that has taken one of its objects as input or produced it as output.

The client service does not manage private keys, or ask the wallet(s) it communicates with to pass along a key.

• Wallet: a component that manages private keys. It can sign orders produced by the client service and ask for reads from the client service.

[lxfind]

Nice! I was just trying to draw the same diagram on my iPad.
One thing though, if we look at the current REST API design in https://docs.google.com/document/d/1BHnoHu6kf0diXCK0ZgUUBNl6xUkVk6qMTr3Qi_zH6BQ/edit, it doesn't actually make any statefulness assumptions, which means it could go directly to the Relayer. In fact, maybe the REST API interface will be the same between ClientService and Relayer, it's just that requests to ClientService is faster (due to local cache), but requests to Relayer could be more accurate (if there are other transactions that didn't go through the same ClientService).

[lxfind]

I am still a bit fuzzy on the concept of ClientService. Is there anything similar to this in any existing blockchains?

[oxade]

@arun-koshy this might be useful

[sblackshear]

I am still a bit fuzzy on the concept of ClientService. Is there anything similar to this in any existing blockchains?

I think the most similar concept is a (part of) a wallet. "Wallet" is an overloaded term that encompasses too many things, but there is a part of an Eth wallet that maintains the user's sequence number, balances in various coins, NFT's the user owns, etc. This is analogous to the local state maintained by the ClientService.

You might also think of the ClientService as a "sparse" full node that only syncs data relevant to the user's address(es), and but ignores the rest of the data going into the chain.

[sblackshear]

I deleted a duplicate comment that seems to have wiped out some other comments--apologies + will not do that again! Here is (I think) everything that got accidentally deleted:

[stella3d]

i was wrong about the client service though - since it's not a full node / full picture of network state, the block explorer wouldn't run the client service, but something else (i think)

[sblackshear]

i was wrong about the client service though - since it's not a full node / full picture of network state, the block explorer wouldn't run the client service, but something else (i think)

I agree with this. Conceptually, the block explorer (at least in my mental model) is a client service that:

• "manages" every non-empty address on the blockchain (instead of just the set of addresses a particular user has keys for)
• does not expose any write API's
• keeps a lot of secondary indexes over the baseline data a normal client service would to facilitate efficient/rich read API's (as Stella mentions)

But that conceptual explanation doesn't mean that it's helpful to implement it that way. Like Stella, my intuition would be to speak directly to the authorities. This avoids needless coupling/exposing the block explorer to concepts/data it doesn't care about (e.g., anything to do with writes).

[stella3d]

@sblackshear a part i'm unclear on is what the explorer will run to keep up-to-date on network state - are authorities the stand-in for a traditional chain's full node, and we can continually talk to them to get a complete picture of state ?

[gdanezis]

Hey @stella3d - services that need to maintain a full replica of the state on all fastx authorities will probably have to use a sync API beyond the client API. This sync API is also used to ensure authorities keep up to date with each other and new authorities get the state so far before validating new transactions.

[gdanezis]

Here is the task that tracks ideas on how to build sync: #194

[stella3d]

perfect, this looks like exactly what it would need.

[arun-koshy]

Thanks for the diagram Sam!

So it sounds like the direct comparison to what we are building from the client side is what Infura/Alchemy are doing for Ethereum

So would it be fair to say that the end output of our client ecosystem should either provide a way where the customer can manage their own servers & state and use our stateless rest api to call into the network (via the relayer from your diagram) OR they can use our stateful API as a service (client service from your diagram) that maintains all this state for them?

[lxfind]

1. AuthorityClient is a component responsible for serializing and sending those 4 Authority calls over the wire to a specific Authority server through TCP. So it's really just the other side of the Authority on the network port. It is stateless in the sense that once an AuthorityClient is created it won't change. Each AuthorityClient maps to an Authority.
2. AuthorityAggregator is a component that abstracts away the fact that FastX has a list of authorities, i.e. AuthorityAggregator will make it look like we only need to talk to one place to do any action. process_order takes an Order and does all the multi-step quorum thing to eventually get a committed cert. Both handle_account_info_request and handle_object_info_request will be responsible for deciding which AuthorityClient to talk to (either random, or quorum, or any other approach) to get the accurate information for return. AuthorityAggregator is also stateless, in that once it's created it won't change.
3. ClientService is the stateful service at the frontline, that manages a bunch of accounts (we can decide whether we actually want ClientService to own private keys). It maintains the list of objects each account owns, and construct Order objects based on the request type. It also should have some mechanism to passively sync client state (or active, on demand).
4. Then at the far left we can have different client implementations: a CLI Client that takes interactive command and calls into ClientService; a REST Client that listens on REST requests; or RPC Client if we need.
5. The MassClient is completely independent at the moment
6. We also want to manage resources in a more efficient way (not marries to the component separation), but has its own mechanism/layer of managing/sharing them.

[gdanezis]

Hey all -- A few thoughts after having slept on our discussion yesterday, and reading @arun-koshy 's REST doc today.

I think the diagram above that has a single "client" dotted box (#275 (comment)) is a little simplifying and misleading. Hear me out:

• A user runs on their machine a client that interacts with the fastx authorities to read state, and sends signed orders to them.
• The orders are signed by a different wallet component on the client as well that holds secret signature keys.
• However, in the context of a web experience the logic that uses the REST API is a webpage from a separate security domain. Thus there is a need to ensure that this webpage is (a) authorized to access the REST API, (b) authorized to talk with the wallet to request signed orders and (c) potentially pre-authorized to perform certain actions (ie get signed orders) without authorization by the user. (In the context of a game it would be really annoying to ask the user all the time to update stuff).
• I think that in the context of a mobile experience it is similar, but I know too little about mobile to say anything intelligent.

So in effect the REST client is NOT in the same trust boundary as the user client, and its access and interactions with the REST or other services need to be mediated and subject to authentication and authorization.

[sblackshear]

Hey all -- A few thoughts after having slept on our discussion yesterday, and reading @arun-koshy 's REST doc today.

I think the diagram above that has a single "client" dotted box (#275 (comment)) is a little simplifying and misleading. Hear me out:

• A user runs on their machine a client that interacts with the fastx authorities to read state, and sends signed orders to them.
• The orders are signed by a different wallet component on the client as well that holds secret signature keys.
• However, in the context of a web experience the logic that uses the REST API is a webpage from a separate security domain. Thus there is a need to ensure that this webpage is (a) authorized to access the REST API, (b) authorized to talk with the wallet to request signed orders and (c) potentially pre-authorized to perform certain actions (ie get signed orders) without authorization by the user. (In the context of a game it would be really annoying to ask the user all the time to update stuff).
• I think that in the context of a mobile experience it is similar, but I know too little about mobile to say anything intelligent.

So in effect the REST client is NOT in the same trust boundary as the user client, and its access and interactions with the REST or other services need to be mediated and subject to authentication and authorization.

Totally agree with this. The oversimplified view applies to what we're shipping for GDC (since there are no web pages, wallets, etc.), but not to any realistic production setup.

[velvia]

@sblackshear and others that diagram above is really nice and would be tremendously helpful to those getting started, like in some kind of architectural overview or README somewhere. I don't really know what a "relayer" is or for.

[lxfind]

@velvia #275 (comment) has something that's closer to what we have today. Agree that we should put these to a README

[oxade]

Arch gets updated often but lately it's mostly steady and agreed we need to be on top of documenting

[velvia]

Arch gets updated often but lately it's mostly steady and agreed we need to be on top of documenting

@oxade I like text-based diagramming tools like Mermaid, so that they can be part of the git history, and now it's officially supported by Github!!!!

https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/

I volunteer to put diagrams in the README. :D

[velvia]

@oxade @lxfind Put the diagram above into README:

#539

[lxfind]

This is all done.