# manta-rs focus API semantics

## Signer

`SDK` uses `manta-wasm-wallet` which can access `manta-rs`, and `manta-rs` sends http requests to `manta-signer` by following API:

- `address() -> Address`: get `zkAddress` of Signer
- `sign(SignRequest) -> SignResponse`: sign a `transaction`, doing zero knowledge proof, generate `TransferPost` for the `transaction`.
- `sync(SyncRequest) -> SyncResponse`: synchronize data from on-chain `Ledger` to Signer.
- `transaction_data(TransactionDataRequest) -> TransactionDataResponse`: retrieve transaction data from `TransferPosts`.

### Request and Response
- `SignRequest`: A `Transaction` together with its `AssetMetadata`.
- `SignResponse`: A vector of `TransferPosts` which describe the transaction in `SignRequest`.
- `SyncRequest`: Consists of the previous `Checkpoint` and on-chain `Ledger` data.
- `SyncResponse`: Consists of the updated `Checkpoint` and a `BalanceUpdate`.
- `TransactionDataRequest`: A vector of `TransferPosts` posted by the user.
- `TransactionDataResponse`: A vector of `TransactionData` corresponding to the request.

### Data Structures
- `Address`: The receiving key. Also called `zkAddress`.
- `Asset`: A pair consisting of an `AssetId` and an `AssetValue`.
- `AssetMetadata`: Metadata of an `Asset`, including its decimal representation and its symbol. It is used for `Asset` display.
- `BalanceUpdate`: Consists of the `Assets` owned by the signer.
- `Checkpoint`: An internal state used to keep the signer and the external `Ledger` synchronised.
- `Proof`: A ZKP verifying that the transition from `Transfer` to `TransferPost` has been properly executed.
- `Transaction`: It is the data structure used to specify the private parameters of a desired `Transfer` when interacting with the signer. In particular, it consists of the transaction type, which can be `ToPrivate`, `PrivateTransfer` or `ToPublic`, the `Asset`, and, if applicable, the receiving `zkAddress`.
- `TransactionData`: Consists of the `Asset` and the random salt underlying a `TransferPost`.
- `Transfer`: The complete description of a transaction, including both public and private inputs.
- `TransferPost`: In `manta-rs` it consists of the public part of a `Transfer` and the `Proof` verifying that the `Transfer` has been executed according to the protocol. After a successful proof verification, it is posted on the `Ledger`.

## Ledger APIs
The Ledger verifies the validity of the transactions through the methods of the `TransferLedger: SenderLedger + ReceiverLedger` trait:
- `is_unspent(Nullifier)`: Checks the `Nullifier` is not a duplicate.
- `has_matching_utxo_accumulator_output(UtxoAccumulatorOutput)`: Checks if the `UtxoAccumulatorOutput` matches the one stored in the `Ledger`.
- `spend(Nullifier, UtxoAccumulatorOutput)`: Posts the `Nullifier` to the `Ledger`, after running `is_unspent` and `has_matching_utxo_accumulator_output`.
- `is_not_registered(Utxo)`: Checks that `Utxo` is not already registered on the `Ledger`.
- `register(Utxo, Note)`: Posts the `Utxo` and the `Note` to the `Ledger` after running `is_not_registered`.
- `check_source_accounts(AssetId, Sources)`: Checks the accounts in `Sources` have enough balance to withdraw from them.
- `check_sink_accounts(AssetId, Sinks)`: Checks that the `Sink` accounts exist.
- `is_valid(TransferPostingKeyRef)`: Checks the `Proof` in `TransferPostingKeyRef` is valid.
- `update_public_balances(AssetId, Sources, Sinks, Proof)`: Updates the public balances after applying `is_valid`.

### Data Structures
- `Note`: A triple associated with a `Utxo`, consisting of:
- A byte acting as an index for rapid synchronization
- An AES-encrypted ciphertext containing the random salt and the `Asset` in the `Utxo`. The contents of this ciphertext have not been verified by the ZKP.
- A Poseidon-encrypted ciphertext containing the random salt and `Asset` in the `Utxo`. The context of this ciphertext have been verified by the ZKP.
- `Nullifier`: A commitment to the hash of a `Utxo` using your proof authorization key. It prevents double-spending.
- `Sink`: A pair consisting of a public `AccountId` and a public `AssetValue`, associated with an `AssetId`. `ToPublic` transactions have one sink.
- `Source`: A pair consisting of a public `AccountId` and a public `AssetValue`, associated with an `AssetId`. `ToPrivate` transactions have one source.
- `TransferPostingKeyRef`: A `TransferPost` after having run `is_unspent`, `has_matching_utxo_accumulator_output`, `is_not_registered`, `check_source_accounts` and `check_sink_accounts`. The only thing left to check is the `Proof`.
- `Utxo`: A cryptographic commitment to an `Asset` under someone's public key (i.e. `zkAddress`) with some randomly generated salt.
- `UtxoAccumulatorOutput`: The root of a Merkle tree whose leaves are hashes of the `Utxos`.

## TransferPost verification APIs
`TransferPosts` can also be verified using the following functions. While most of these are equivalent to their `Ledger` counterparts,`has_valid_proof` and `has_valid_authorization_signature` have independent meaning, as they don't need to be checked against the `Ledger`.
- `ReceiverPost::validate(&self, Ledger)`: runs `is_not_registered` against `Ledger`.
- `SenderPost::validate(&self, Ledger)`: runs `has_matching_utxo_accumulator_output` and `is_spent` against `Ledger`.
- `TransferPost::check_public_participants(Sources, Sinks, Ledger)`: Checks `Sources` and `Sinks` are valid against `Ledger`.
- `TransferPost::has_valid_authorization_signature(&self)`: Checks the `AuthorizationSignature` of the `TransferPost` is valid.
- `TransferPost::has_valid_proof(&self)`: Checks the `Proof` in `TransferPost` is valid.
- `TransferPost::validate(&self, Ledger, Sources, Sinks)`: Runs all the functions above.

### Data structures
- `AuthorizationSignature`: A signature necessary to authenticate `PrivateTransfer` and `ToPublic` transactions. It binds the spending key to the proof authorization key, necessary to compute the `Nullifier`.
- `ReceiverPost`: A pair consisting of `Utxo` and a `Note`. It is part of a `TransferPost`.
- `SenderPost`: A pair consisting of a `UtxoAccumulatorOutput` and a `Nullifier`. It is part of a `TransferPost`.

## Other verification APIs
Here we include those verification APIs which don't belong to the categories above.

- `TransactionData::check_transaction_data(&self, Address, Utxos)`: checks that it is possible to reconstruct `Utxo` from `TransactionData` and `Address`.

## Wallet
The `Wallet` is essentially a `Signer` with a `Balance` and an internal `Ledger`. It shares most of its methods with `Signer`, but it has one that wraps all the methods up:
- `post(Transaction, AssetMetadata)`: runs `sync`, then `sign(SignRequest(Transaction, AssetMetadata))` and finally tries to post the resulting `TransferPosts` on the `Ledger`, which will run the checks above on them.