Rename "Ledger" to "LedgerPlugin"?

[sappenin]

Looking at the JS interface, they're calling the main interface "LedgerPlugin" which kind of makes sense to me since the thing currently called "Ledger" in the Java interface isn't really the Ledger itself, but an interface of sorts to the leger.

Any objection to renaming the Java interface to align with the JS interface/impl?

[sappenin]

Also, I notice that the Ledger class is missing some methods like "connect" and "disconnect". Perhaps I'm misinterpreting the intent of the Ledger.java interface?

[adrianhopebailie]

This Java implementation is not a direct port of the JS because Java allows us to define proper interfaces so we can do things a bit differently.

For this reason Ledger is not called LedgerPlugin, it's the interface of a ledger (as opposed to a ledger plugin).

We could define something like LedgerClient that extends Ledger and has connectivity functions like connect and disconnect?

We could also define something called LedgerPlugin that extends Ledger but is specifically intended to run in the connector space.

[sappenin]

Cool, thanks for clarifying. Though, it's still not clear to me exactly what the Ledger interface is defining then (and it's probably just the semantics that are throwing me off).

In my mind, an actual ledger can exist outside of the realm of ILP (e.g., a PayPal Ledger). There's also this concept of an ILP-Ledger, which has certain constraints per RFC1.

If you'll indulge me a bit, I'd like to "think aloud" and list some different concepts floating around in my mind related to all of this -- to see if I'm even defining things properly. Once I fully understand those concepts, I think it will be easier to wrap my mind around naming.

So, here goes:

1. Ledger: something like here, "A book or other collection of financial accounts of a particular type." The key take-away for me is that this concept is something independent of ILP -- it exists as a systems term or accounting term or whatever that existed even before ILP was invented.
   So, calling the main interface of java-ilp-core just "Ledger" seems to imply that in order to upgrade an existing Ledger code-base written in Java to become ILP conformant, one would need to update that implementation's "Ledger" to implement the Ledger interface from ilp-core (?). However, it's likely that such a Ledger already implements a different Ledger interface (this isn't really so terrible due to Java package naming differentiation, but as a concept, it seems like we want to use a term slightly different from just Ledger).
2. ILP Ledger: A ledger that conforms to the requirements of the Interledger protocol (see RFCs). For example, an ILP-Ledger can be orchestrated by an ILP connector (host?) to move assets around. Bringing things down a bit, an example of an ILP-Ledger that relates to java-ilp-core would be a Ledger written in Java that exposes some functionality that conforms to what is currently defined in Ledger.java. (Is this correct? This seems to be the main concept I'm struggling to understand). Additionally, the ILP-Ledger will publish events in response to various ILP activities (e.g., see ILP Core Events).
3. ILP Ledger Event Publisher: The system that publishes events in response to the ILPLedger "doing things". Perhaps this is the same as the ILPLedger concept above? Might be worth having its own interface though.
4. ILP LedgerClient: A system that connects to and communicates with an ILP-Ledger, and possibly instructs the ILP-Ledger to operate on the underlying Ledger. An example of this might be a process running on my laptop that connects to a web-service (said service exposes the ILP-Ledger functionality), which then can orchestrate its underlying Ledger.
5. ILP Ledger Event Subscriber: A system that subscribes (in one form or another) to events that get kicked off from an ILP Ledger Event Publisher implementation.
6. Ledger Plugin: This is really just a concept I'm taking from RFC4, but it seems like this would encompass possibly the things above? I always understood the "plugin" defined in RFC4 to be a piece of code that can be used to connect an existing ledger to ILP. So, maybe that would be Javascript code (in the case of RFC4) that runs in the same process as the existing ledger (that feels like a plugin) or maybe it would be code that runs in its own process and merely bridges between the existing ledger and ILP (that feels more like a Ledger Client). In any event, it would be helpful for me to understand at a conceptual level how RFC4 and what we're defining here in java-ilp-core map to each other.

Ok, I'm sure what I've written above is not entirely accurate, so feel free to clarify and propose some new terminology and descriptions.

Overall, I suppose I'd like to explore whether we should rename Ledger.java to something like IlpLedger.java. Thoughts?

[adrianhopebailie]

However, it's likely that such a Ledger already implements a different Ledger interface (this isn't really so terrible due to Java package naming differentiation, but as a concept, it seems like we want to use a term slightly different from just Ledger).

Right, in this case you'd use an appropriate pattern to create an adaptor that conforms to the ILP-Ledger interface and sits on top of the existing ledger.

Is this correct? This seems to be the main concept I'm struggling to understand

Yes. I guess we could call it ILP ledger but I don't see the value really. Everything in this package is ILP-something. What would calling it ILP ledger give us?

Also, consider that many of the methods on this interface are not ILP specific.

ILP Ledger Event Publisher

Logically, I would call the ledger itself an event emitter. How different platforms handle events means the actual class models differ. I have defined a bunch of event definitions and then allow the ledger to accept event handler registrations. So the ledger is the emitter and something else is the handler.

This can plug into a distributed notification framework where the handler is a publisher that pushes these notifications across network boundaries or similar.

ILP LedgerClient

👍

Ledger Plugin

This is a component designed to run in the same process as the connector and to expose a standard interface for this. So, it is very similar to an ILP Ledger client except that it is assumed that the ledger it connects to does not conform to the ILP Ledger interface.

In general, I'd say there are three ways we can interface a connector and ledger:

1. The ledger exposes the standard ledger interface we define and the connector consumes this. By defining this as an interface we can use various platform specific RPC technologies to do this.
2. The ledger exposes a standard platform agnostic interface (RESTful). Connectors implement a standard client for this interface and can connect o any ledger that exposes it.
3. The connector runs a client (plugin) that exposes a standard interface to the connector but connects via a ledger specific interface to the ledger.

[sappenin]

Yes. I guess we could call it ILP ledger but I don't see the value really. Everything in this package is ILP-something. What would calling it ILP ledger give us?

Good point - adding ILP to Ledger to call it ILPLedger.java does feel a bit redundant. For me, the use of the name Ledger.java seemed to imply that in order to be ILP compliant, my Ledger would need to implement this interface -- in other words, it seemed to exclude the other options like a LedgerClient or LedgerPlugin as you describe below.

I see that's not the case, however, so perhaps just adding some Javadoc into Ledger.java to say this is the "ILP view of a Ledger", or "An abstraction layer for a Ledger for purposes of ILP" would help clarify that this is ILP's view of a Ledger, not necessarily the ledger itself. For me it's easier to reason about this being more of a LedgerAdapter or LedgerView, but I see why one might prefer to call it just Ledger for simplicity.

Feel free to close this ticket if you still think Ledger.java is best. If you're agreeable, I'll open a separate issue/PR with some Javadoc for Ledger.java?

Logically, I would call the ledger itself an event emitter...

To clarify, when you say "the ledger itself", you're meaning that the implementation of Ledger.java is the event emitter, yes? (Again, use of the word "Ledger" is ambiguous for me between the Ledger itself, and a Ledger.java implementation, which I'm viewing as the ILP interface-to/view-of the Ledger itself).

...This can plug into a distributed notification framework...

Makes sense, 👍.

In general, I'd say there are three ways we can interface a connector and ledger: 1.) The ledger exposes the standard ledger interface we define and the connector consumes this. By defining this as an interface we can use various platform specific RPC technologies to do this.

Can you clarify which type of platform specific RPC is envisioned here that would be able to formally expose Ledger.java to a remote system? EJB remote interfaces come to mind as an example, but is this a common pattern for many existing Ledgers today? I would have expected something closer to your option 2 (below) to be the norm as opposed to remote systems using an actual Java interface to communicate across network boundaries, such as from a Connector to a Ledger.

2.) The ledger exposes a standard platform agnostic interface (RESTful). Connectors implement a standard client for this interface and can connect to any ledger that exposes it.

Is an example of this something like a Java client built on top of a formalized SPSP flow?

3.) The connector runs a client (plugin) that exposes a standard interface to the connector but connects via a ledger specific interface to the ledger.

It seems like this last option (3, the Connector Plugin) will be the interface that every connector might want to implement for any Connector->Ledger scenario.

For example, to accomplish (1), the Connector uses a ConnectorPlugin implementation which internally uses an impl of Ledger.java to actually talk to a Ledger. To accomplish (2), a Connector uses a ConnectorPlugin implementation that uses an implementation of a standardized LedgerClient.java to talk to the Ledger's generic interfaces. To accomplish (3), a Connector uses a ConnectorPlugin implementation that uses a custom client to talk to a Ledger.

[sappenin]

@adrianhopebailie I'm going to close this one. I think what we have currently as Ledger makes sense to me now that I've had some time in the code. Feel free to re-open if you feel otherwise.