Signatures

Signature Structure

To interact with the system, users have to send messages containing orders they wish to execute. The following order types are currently supported:

  • Trade order, declaring intent to sell a certain amount of a certain token in exchange for a different token at a certain ratio.

  • Transfer order, requesting funds to be transferred from one vault to another.

The order data is sent directly to the exchange through an interface exposed there, in addition to a signature over all its fields that is verified by the proof system.

The signature is constructed as follows:

\[\textrm{ECDSA}(H(H(w_1, w_2), w_3), k_{private})\]

\(H\) is the Pedersen hash function, \(k_{private}\) is the user’s private key, and the words \(w_1\), \(w_2\) and \(w_3\) are three \(256\)-bit words containing the data required for the signature, as described below.

Message Word Definition

\(w_1\) is the token ID to be sold (or transferred).

\(w_2\) depends on the order type:

  • In a trade order, \(w_2\) is the token ID to be bought.

  • In a transfer order, \(w_2\) is the transfer target’s public key.

\(w_3\) is a bit-packed message whose lower 245 bits conform to the format described below, depending on the order type.

         +---+---------+---------+-------------------+-------------------+---------+-------+
#bits    | 4 |   31    |   31    |        63         |        63         |   31    |  22   |
         +---+---------+---------+-------------------+-------------------+---------+-------+
label      A      B         C             D                   E              F        G

Where:

  • A: the order type, 0 for trade order or 1 for transfer order.

  • B: the ID of the vault from which the user wants to take funds.

  • C:

    • In case of a trade order, the ID of the vault into which the user wants to receive funds.

    • In case of a transfer order, the ID of the vault to receive the transfered funds.

  • D: the amount to be sold / transfered.

  • E: the amount to buy in exchange (0 in case of a transfer order).

  • F: A nonce for the transaction.

  • G: the expiration timestamp, in hours since the Unix epoch. For example, for the order to expire 24 hours from the beginning of the current hour, set the timestamp to \(\left\lfloor{\frac{t_{unix}}{3600}}\right\rfloor + 24\).

Examples

Suppose Alice and Bob are two users trading tokens X (whose ID is 100) and Y (whose ID is 200), with the following setup:

Transfer Example

Suppose that Alice wants to transfer \(25X\) from her vault with ID 7 to Bob’s vault with ID 12. In this case she will sign the following message:

\[H(H(100, k_{public}^{Bob}), m)\]

Where \(m\) is formatted as follows

         +---+---------+---------+-------------------+-------------------+-----------+-------+
value    | 1 |    7    |   12    |        25         |         0         |   nonce   |  ts   |
         +---+---------+---------+-------------------+-------------------+-----------+-------+
label      A      B         C             D                   E                F         G

Order Example

Suppose that now Alice wants to trade \(9000X\) from her vault with ID 7 for \(15000Y\), to be deposited in her vault with ID 4 if the trade succeeds. In this case, she will sign the following message

\[H(H(100, 200), m)\]

Where \(m\) is formatted as follows

         +---+---------+---------+-------------------+-------------------+-----------+-------+
value    | 0 |    7    |    4    |       9000        |      15000        |   nonce   |  ts   |
         +---+---------+---------+-------------------+-------------------+-----------+-------+
label      A      B         C             D                   E                F         G