Delegation state

Goals

1. Allow a wallet to have an arbitrary number of stake keys
2. Ensure those stake keys can be automatically discovered on-chain
3. Ensure the wallet is always aware of all stake keys it registers, even in the case of concurrent user actions on multiple wallet instances, and old wallet software.

How

We track a consecutive range of keys that is extended with delegation of the next unused key, and shrunk with key de-registration. We use a PointerUTxO to ensure that transactions changing the state can't be accepted to the ledger in any other order than intended. We also need some special care regarding stake key 0, which old wallet software could try to de-register.

Diagram

Diagram of states, where the list denotes active (registered and delegating) keys.

Here we assume the minUTxOValue is 1 ada.

Note that intermediate steps for the PointerUTxO should be skipped within a transaction. E.g. to transition from [] to [0,1,2] we should deposit 1 ada to key 3, skipping key 2.

See the implementation of setPortfolioOf and applyTx for more details.

┌────────────────────┐           ┌────────────────────┐                     ┌────────────────────┐            ┌─────────────────────┐
│                    │           │                    │                     │                    │            │                     │
│                    │           │                    │       Pointer       │                    │            │                     │
│                    │──────────▶│                    │ ──────deposit──────▶│                    │ ─────────▶ │                     │ ─────────▶
│                    │           │                    │                     │       [0,1]        │            │       [0,1,2]       │
│         []         │           │        [0]         │                     │1 ada held by key 2 │            │ 1 ada held by key 3 │
│                    │           │                    │                     │                    │            │                     │
│                    │           │                    │       Pointer       │                    │            │                     │
│                    │◀──────────│                    │ ◀─────deposit ──────│                    │◀────────── │                     │◀──────────
│                    │           │                    │       returned      │                    │            │                     │
└────────────────────┘◀──┐       └────────────────────┘                     └────────────────────▲            ▲─────────────────────▲            ▲
                         └───┐                                                     │       ▲     └─┐         ┌┘      │       ▲      └─┐         ┌┘
Normal states                └───┐                                                 │       │       └─┐     ┌─┘       │       │        └─┐     ┌─┘
                                 └───┐                                             │       │         └─┐ ┌─┘         │       │          └─┐ ┌─┘
╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳└───┐╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳╳│╳╳╳╳╳╳╳│╳╳╳╳╳╳╳╳╳╳╳│ │╳╳╳╳╳╳╳╳╳╳╳│╳╳╳╳╳╳╳│╳╳╳╳╳╳▶     ├─┤
                                         └───┐                                     │       │         ┌─┘ └─┐         │       │          ┌─┘ └─┐
States caused by                             └────┐Pointer                         ▼       │       ┌─┘     └─┐       ▼       │        ┌─┘     └─┐
old wallet                                        └deposit                  ┌────────────────────┐─┘         └┬─────────────────────┐─┘         └─
de-registering                                     returned─┐               │                    │            │                     │
stake-key 0                                                 └────┐          │                    │ ─────────▶ │                     │ ─────────▶
of multi-stake                                                   └────┐     │                    │            │                     │
key wallet                                                            └──── │        [1]         │            │        [1,2]        │
                                                                            │1 ada held by key 2 │            │ 1 ada held by key 3 │
                                                                            │                    │            │                     │
                                                                            │                    │◀────────── │                     │◀──────────
                                                                            │                    │            │                     │
                                                                            │                    │            │                     │
                                                                            └────────────────────┘            └─────────────────────┘

Construct the initial delegation state.

All stake keys worth listing to the user.

May include: 1. Active stake keys 2. The next un-active key

NOTE: In theory we might want also present stake keys that are unexpectedly registered, as they could be de-registered to reclaim the deposit, but this should in-practice never happen.

If sn denotes the state with n registered and delegating keys: >>> presentableKeys s0 [0] >>> presentableKeys s1 [0, 1] >>> presentableKeys s2 [0, 1, 2]

For testing. Returns all registered and delegating stake keys.

The internal state, without the account key.

TODO: Perhaps we should model this as S = S1 * S2, where S1 = Bool, S2 = ix * UTxOPointer - having two "concurrent" states tracking stake keys, where the first one is identical to legacy single-stake key wallets.

Maybe that would help simplify applyTx and setPortfolioOf ...

Is key 0 still registered? For compatibility with single-stake-key wallets, we need to track this.

>>> activeKeys (More (toEnum 3) p ValidKey0)
[0, 1, 2]

>>> activeKeys (More (toEnum 3) p MissingKey0)
[1, 2]

(pseudocode; requires a bit more boilerplate to compile)

See the implementation of applyTx for how it is used.

A transaction type specific to DelegationState .

Intended to be converted both from and to a more real transaction type.

When constructing a real transaction from Tx , these outputs should appear before other outputs. In the theoretical event that there's also a user-specified output with the same payment key as the pointer output, applyTx will track the first one as the new pointer.

Apply a Tx to a DelegationState .

Expects the PointerUTxO to be correctly managed, and will panic otherwise.

Given a DelegationState , produce a Tx registering or de-registering stake-keys, in order to have n stake-keys.

E.g. setPortfolioOf s0 _ _ 2 creates a tx which after application causes the state to have activeKeys == [0,1]

Returns Nothing if the target n is already reached.