# CL L2 V0

This repo is a sandbox for the Cardano Lightning's L2 (V0).

A key aim of this repo is to try and assess available libraries in order to
establish our key dependencies.

## Setup

This repo use nix flakes with a shell available. Otherwise ymmv.

## Context

CL depends on the use on signing/verification key pair cryptography. The signing
key may be used to handover all the participants funds. The signing key must be
handled with care.

A router node must run their infrastructure on highly available machines, in
order to provide good service to their partners. The router might choose to use
an infrastructure provider to host their nodes. The router must produce the
signatures for cheques and snapshots in the course of standard channel
operations. A priori the machine will contain signing keys. What if the machine
is compromised?

An attacker with access to the machine could send all funds to the partner of
the channel, or produce a tx that a partner signs, making it a valid mutual tx.
In either case, they are at the detriment of the router.

Instead, we may outsource the signing process to a separate machine - the
signing server. This sever can:

- serve requests to only whitelisted requesters. It can be more easily protected
  from ddos type attacks and probing by an attacker.
- has minimal, relatively fixed, API. It will receive fewer updates each of
  which can be reviewed more thoroughly, and have shorter/tighter software
  supply chains, than might be true for the general service on the HA machine.

In addition, the signing service could be split using, say, FROST.

## Design

### Data

#### Persistent keys

These are the signing keys available to the machine and found at startup of the
service.

#### Ephemeral keys

Perhaps also called proxy keys.

An ephemeral key consists of the following properties:

1. Verification key
1. Persistent key
1. Expires at
1. Signature

### Signing Server Actions

#### Add

An add is performed by "admin" to create new ephemeral keys.

An `add` request has the following fields

1. Verification key
2. Persistent key
3. Expires at
4. Signature

The request is deemed valid

1. The persistent key is in the database
1. The signature is valid wrt the persistent key, and the payload created by
   `(verification_key, expires_at)` (with some prefix?)

The result of a valid `add` request is the ephemeral key is added to the
database with the obvious fields.

The response is either `Ok()` or `Error("help message!")`

#### Sign

A sign action is the "standard" action that will occur.

A `sign` request has the following fields

1. Verification key
2. Payload
3. Signature

The request is deemed valid

1. The verification key exists in the database
1. The verification key has not expired
1. The signature is valid wrt the payload and verification key
1. The payload is "sensible" (TBC) - this is context specific.

The response to a valid request

1. The signature produced by the persistent key associated to the verification
   key for the same payload.

#### Revoke

A revoke is the opposite of add. It is also performed exclusively by admin.

An `revoke` request has the following fields

2. Verification key
3. Signature

The request is deemed valid

1. The verification key is in the database
1. The signature is valid wrt the associated persistent key, and the payload
   created by `verification_key` (with some prefix?)

The result of a valid `revoke` request is the ephemeral key is removed from the
database.

The response is either `Ok()` or `Error("help message!")`

#### SIMPLIFICATION

The `add` and `revoke` endpoints are needed only by admin, and infrequently, or
in case of emergency. In contrast, `sign` is needed with relatively high
frequency, and called by less trusted machines.

Thus, we assume that admin accesses the machine directly and simply adds the
ephemeral keys to the db. This does not require a valid signature - if the pub
key is registered, then a signature request is honored.

### Client server actions

#### Demo task

Some way to trigger the client service to make a request to the server.

## Notes

### sqlx

The sqlx tool has a cli (available via the flake). This can handle migrations
provided its opinionated design choices are adopted. See
[here](https://docs.rs/sqlx/latest/sqlx/migrate/trait.MigrationSource.html).

```sh
export DATABASE_URL=sqlite:./db/cll2v0.db
sqlx database create
sqlx migration run
```

The database must be initialised before starting the application.

### libp2p

TODO