Considering go-nitro's client API

[NiloCK]

Work towards #904 has brought about changes to go-nitro's public API, ie, the API of client.Client.

Currently, the API is:

CreateLedgerChannel(Counterparty types.Address, ChallengeDuration uint32, outcome outcome.Exit) directfund.ObjectiveResponse
CloseLedgerChannel(channelId types.Destination) protocols.ObjectiveId

CreateVirtualPaymentChannel(Intermediaries []types.Address, CounterParty types.Address, ChallengeDuration uint32, Outcome outcome.Exit) virtualfund.ObjectiveResponse
CloseVirtualChannel(channelId types.Destination) protocols.ObjectiveId

Pay(channelId types.Destination, amount *big.Int)

CompletedObjectives() <-chan protocols.ObjectiveId
FailedObjectives() <-chan protocols.ObjectiveId
ReceivedVouchers() <-chan payments.Voucher

Some goals for the API:

1. be small(ish). Its documentation should fit on a single page.
2. minimize requirements for domain expertise (ie, knowledge of protocol internals) on the part of developers consuming it
3. minimize requirements for the consuming application to manage & store information related to:

• the network topology (ie, who has connections with who)
• its running channels

[NiloCK]

CreateVirtualPaymentChannel

Towards 2 and 3, I think that we should aim for the following change:

// replace this
CreateVirtualPaymentChannel(Intermediaries []types.Address, CounterParty types.Address, ChallengeDuration uint32, Outcome outcome.Exit) virtualfund.ObjectiveResponse

// with this
CreateVirtualPaymentChannel(CounterParty types.Address, ChallengeDuration uint32, Outcome outcome.Exit) virtualfund.ObjectiveResponse

Current usage of the API is limited to tests which specifically orchestrate the shape of the network from an all-knowing perspective. A real-world usage of the current API would require the consuming applications to coordinate on determining a working ledger path, but this 'pathfinding' operation is part of nitro's domain and should be encapsulated as much as possible.

Obstacles to this change

A nice thing about the existing method is that it contains all of the information required to compute the channelID, which can then be returned synchronously. Current usage is for the client to

• request creation of a channel
• wait for that objective to complete via the CompletedObjectives() chan
• send payments via Pay(channelId types.Destination, amount *big.Int) after it learns the objective has completed

A CreateVirtualChannel api call which doesn't supply the intermediaries will need a different way to account for sent and completed requests, since the channelID won't be computable in advance.

[lalexgap]

Current usage of the API is limited to tests which specifically orchestrate the shape of the network from an all-knowing perspective

I think this brings up some interesting questions about how the network is set up and run! Currently it's pretty primitive, every client manually adds peers, and then specifies the intermediaries to use when creating the channel. Based on our current libp2p message service if Alice wants to create a channel with Bob she needs to know the url/port for Bob's message service and all the intermediaries.

I think this means the network topology is essentially constructed by the application, not go-nitro. This might be fertile ground for an RFC? We could consider various ways on how we manage/discover the network. I think there's also trade offs to consider between making our API easy to use versus allowing application developers to embed go-nitro in their applications with their own networks/messaging.

but this 'pathfinding' operation is part of nitro's domain and should be encapsulated as much as possible.

I think this could be true in certain use cases but not necessarily all? When pathfinding there may be trade-offs between one route and another and the application may not have the full context to make that decision. For example let's say Alice is trying to open a virtual channel with Bob. Let's say there's two hubs she could use for the virtual channel: Irene's Hub and Joe's Hub. Irene's hub charges more fees but has better reliability/response time. I think it's a non-trivial decision for go-nitro to make, as has no way of knowing what Alice values more.

There's lots of way to mitigate this (go-nitro could return route "summaries" or Alice could provide something like our policyManager to make decisions) but I think it probably needs some consideration?

A CreateVirtualChannel api call which doesn't supply the intermediaries will need a different way to account for sent and completed requests, since the channelID won't be computable in advance.

Assuming go-nitro is handling pathfinding, couldn't CreateVirtualChannel return a channelID even when called without intermediaries? When you call CreateVirtualChannel go-nitro would determine the intermediaries it wants to use so, and then generate the channel id based on them.

This does mean the application developer can't precompute the channel ID and relies on CreateVirtualChannel to determine the channel id, but that seems reasonable (and how we already use it in practice).