# Wallet — Improvements for Exchanges

Cryptocurrency exchanges would like to use `cardano-wallet` in a certain way. This document specifies two HTTP endpoints that would help them.

# Background / Requirements

When using `cardano-wallet`, exchanges do *not* create one ``{walletId}`` per customer. Instead, they create a single wallet, and within this wallet, they

* generate 1 address for a customer
* assign that address to the customer
* scan the address
* detect an incoming deposit
* increment the customers off chain balance (in their DB)
* move the funds into a withdraw wallet (this is what CF recommends them doing: 1 deposit wallet, 1 withdraw wallet, migrate from wallet 1 to wallet 2 on regular intervals.)

Note that this is at odds with the current assumptions of `cardano-wallet`, which treats all UTxO belonging to a single wallet as interchangeable, regardless of their addresses. In contrast, exchanges do want to associate incoming UTxO with different addresses to different customers. When using `cardano-wallet`, they currently do this by relying on underspecified behavior of how the wallet manages addresses. As this behavior has changed from Byron to Shelly, exchanges have not upgraded to Shelley-style addresses.

Shelley-style addresses have the following advantages over Byron-style addresses:

* The character encoding [bech32][] offers better protection against address misspellings by end users.
* Addresses are generated from a clearly specified hashing algorithm ([CIP-1852][], [BIP-32][]), as opposed to relying on the internals of Haskell's `StdGen` implementation.

[bech32]: https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki
[cip-1852]: https://cips.cardano.org/cips/cip1852/
[bip-32]: https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki

# Specification

Here, we specify the semantics of two endpoints that

* would help exchange users meet the requirements above,
* have small implementation cost.

## Endpoint `GenerateAddress`

### Semantics

* HTTP verb: `POST`
* HTTP path: *to be determined*
* Input value: Natural number `index` which is a numerical index representing a customer.
* Output value: One `Bech32`-encoded address which satisfies:
* The wallet is able to spend this address.
* Distinct input `index` result in distinct output addresses.
* The wallet endpoints `[X,Y] (to be specified precisely)` never create a transaction with a change output that has this address.
* Side effect: Beginning from the slot (time) where this procudure has finished (or a short time thereafter), the wallet recognizes UTxO with this address and includes them in its total UTxO.

### Notes

* The mapping from `index` to address is best done by using [BIP-32][] with the address path

    m / purpose' / 1815' / 0' / 0 / index

* The side effect implies that a wallet with this endpoint does *not* follow the [BIP-44][] or [CIP-1852][] standards, as they require address discovery with an address gap.
* Consequently, in the above address path, we need to use a value for `purpose` that is different from an existing standard (currently `1852`–`1855`).

[bip-44]: https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki

* When restoring the wallet from scratch, the user needs to call this endpoint once for each customer. We could offer an additional endpoint that executes the side effect of this endpoint for a range `index = [0 … someNumber]`.

### Implementation details

As the semantics does not allow BIP-44 style address discovery, we cannot reuse an existing address state type `s`, and need to implement a new type. This includes implementations for

* `AddressBookIso s` — As no addresses are discovered on-chain, we have `Discoveries s ~ ()`; the `Prologue s` contains the (bidirectional) mapping from address to `index`.
* `GenChange s` — For simplicity, we should use a single change address, `m / purpose' / 1815' / 0' / 1 / 0`. In order to satisfy the endpoint semantics, this address needs to be distinct from all the addresses generated by the endpoint.
* `IsOurs s` — by looking up an address in the `Prologue s`. This lookup needs to consider the change address as well.
* `PersistAddressBook s` — A new table in the database that stores the mapping from indices to addresses.

## Endpoint `QueryAddress`

### Semantics

* HTTP verb: `GET`
* HTTP path: *to be determined*
* Input value: `Bech32`-encoded `address` which was previously generated by the `GenerateAddress` endpoint.
* Output value:
* The subset of the `UTxO` that currently belong to the wallet which have this `address`. (And summary data compute from this subset, e.g. the total balance, or the assets)
* :warning: This subset of `UTxO` will be modified non-deterministically when the user makes a transaction with this wallet through another endpoint. The endpoints `[X,Y] to be specified` will never create change outputs which add to this set, but they can subtract from this set, and they can add to it when outputs are specified.
* Side effect: None.

### Notes

This endpoint is sufficient to detect deposits to the wallet at a specific address, but the wallet still mostly treats all addresses as interchangeable when making transactions.

### Implementation details

This endpoint can be implemented straightforwardly as a `filter` of the `UTxO` for the current checkpoint. However, the caveat :warning: applies — the wallet does not partition the `UTxO` in the sense that transactions are only allowed within a single `UTxO`.