mwixnet/doc/swap_api.md

# Swap Server API

## Overview

The Swap Server provides a single JSON-RPC API with the method `swap`. This API is used by clients to initiate the mixing process for their outputs, obscuring their coin history in a transaction with other users.

## SWAP

### Request
The `swap` method accepts a single JSON object containing the following fields:

- `onion`: an `Onion` data structure, which is the encrypted onion packet containing the key information necessary to transform the user's output.
- `comsig`: a Commitment Signature that proves the client knows the secret key and value of the output's commitment.

#### `Onion` data structure

The `Onion` data structure consists of the following fields:

- `pubkey`: an ephemeral pubkey to as the onion originator's portion of the shared secret, represented as an `x25519_dalek::PublicKey`.
- `commit`: the Pedersen commitment before adjusting the excess and subtracting the fee, represented as a 33-byte `secp256k1` Pedersen commitment.
- `data`: a vector of encrypted payloads, each representing a layer of the onion. When completely decrypted, these are serialized `Payload` objects.

Each entry in the `enc_payloads` vector corresponds to a server in the system, in order, with the first entry containing the payload for the swap server, and the last entry containing the payload for the final mix server.

#### `Payload` data structure

A `Payload` represents a single, decrypted/peeled layer of an Onion. It consists of the following fields:

- `next_ephemeral_pk`: an `xPublicKey` representing the public key for the next layer.
- `excess`: a `SecretKey` representing the excess value.
- `fee`: a `FeeFields` value representing the transaction fee.
- `rangeproof`: an optional `RangeProof` value.

### Response

A successful call to the 'swap' API will result in an empty JSON-RPC response with no error.

In case of errors, the API will return a `SwapError` type with one of the following variants:

- `InvalidPayloadLength`: The provided number of payloads is invalid.
- `InvalidComSignature`: The Commitment Signature is invalid.
- `InvalidRangeproof`: The provided rangeproof is invalid.
- `MissingRangeproof`: A rangeproof is required but was not supplied.
- `CoinNotFound`: The output does not exist, or it is already spent.
- `AlreadySwapped`: The output is already in the swap list.
- `PeelOnionFailure`: Failed to peel onion layer due to an `OnionError`.
- `FeeTooLow`: The provided fee is too low.
- `StoreError`: An error occurred when saving swap to the data store.
- `ClientError`: An error occurred during client communication.
- `SwapTxNotFound`: The previous swap transaction was not found in data store.
- `UnknownError`: An unknown error occurred.

### Example

Here is an example of how to call the 'swap' API:
```json
{
  "jsonrpc": "2.0",
  "method": "swap",
  "params": {
    "comsig": "09ca34db2ac772a9a0e954b4ae2180ba936d8f96219824fe7ec1f5439bef3a0afe7e18867db3d391f37260285feea38ff740b0b49196a4b0a7910c1a72ceca1c5a3e4a53d6e06ffb0536f0dad78812a72ef14e6ff83df8d0dd2aa71615fb00fbe2",
    "onion": {
      "commit": "0962da257e8c663d1a35128cf87363657ae6ec4a3c78fda4742a77e9c4f17e1a20",
      "data": [
        "fd06dd3e506b1c1e76fd6546beec1e88bb13e7e13be7c02a7e525cd22c43d5dc7a906c77e5c07b08d7a5eeb7e7983b87376b02a33f7582ffc1bf2adac498fefbc2dba840d76d4c8e945f",
        "ecead273b9b707d101aae71c2c7cb8ce3e7c95347aa730015af206baaf37302df48e5e635ecc94ddf3eee12b314e276f23e29e7dde9f30f712b14ea227801719ecdd1a53999f854a7f4878b905c94905d5f1bfbb4ad9bcf01afeb55070ebcc665d29b0a85093b4d134a52adc76293ad9e963a9f7156dcfc95c1c600a31b919495bf6d3b7ec75eeffcc70aef15b98c43c41468f34b1a96c49b9e20328849a3b12c84d97893145a65d820c37dae51eba62121d681543d060d600167ede3a8c6e807a5765c5ebb2d568366c89bba2b08590a4615822ca64fb848e54267b18fc35fb0f9f6834f1524d7e0da89163e5385de65613e09fed6fec8d9cc60354baa86131b80aa1c8cd5be916a3d757cd8e8253c17158555539a2f8e4d9d1a4b996b218b1af3e7b28bdf9e0f3db2ea9f4d5e11d798d9b7698d037e69df3ca89c2165760963a4d80207917a70a4986d7df83b463547f4d704d28b1eec2e5a93aa70b5b7c73559120e23cd4cfbf76e4d2b21ef215d4c0210001c17318eba633a3c177c18ef88b6c1718e11c552cc77b297dab5c1020557915853434b8ca5698685b3a66bba73164e83d2440473ebb0591df593e0264b605dc3b35055a7de0d40c5c7cc7542dcbe5ade436098dd41e1ac395d2d0baf5c82fdd5932b2e182f8f11a67bccc90e6e63ec8928bd7f0306c6949122fadf12493a7de17f7bfad72501f4f792fca388b3614d6eb3165d948d7c9efe168b5273b132fa27ea6e8df63d70d8b099a9220903b02898b5cc925010ebfab78ccceb19a9f2f6d6e0392c4837977bf0e3e014913e154913c0204913514684f64d7166b3a7203cbab9dddd96ed7db35b4a17fec50abd752348cdf53181ddd6954bc1fb907ed86206dcf05c04efb432cb6ba6db25082b4ce0bf520e3c508163b44c82efaa44b2ec904ddd938a0b99044666941bc72be58e22122027c2fcbc4299e52bc29916eb51206c41e618bce1a5c0d859d116807217282d0883fdabe6f9250cda63082f71fbf921b65ab17cd9bfb0561c4cabe1369c7d6a85c51c0e4f43f51622e70ab4eb0e3fab5"
      ],
      "pubkey": "500b161d3bbd9249161d9760ba038d9805be86c0e5273782303a67cda50edb5a"
    }
  },
  "id": "1"
}
```