Spot Trading

To interact with the system, users have to send messages containing orders they wish to execute. The following order types are currently supported (the withdrawal transaction doesn't require a signature and therefore, is ignored here):

  • Limit Order, declaring intent to sell a certain amount of a certain asset in exchange for a different asset at a certain ratio.

  • Conditional Transfer, requesting funds to be transferred from one vault to another if some on-chain event was recorded.

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

The transaction is sent directly to the application through an interface exposed there, and the validity of the signature over all the fields is verified by the proof system.

In the case of Limit Order and Transfer, the signature is constructed as follows:

​ECDSA(H(H(w1,w2),w3),kprivate)ECDSA(H(H(w_1, w_2),w_3), k_{private})​

In the case of Conditional Transfer, the signature is constructed as follows:

​ECDSA(H(H(H(w1,w2),w4),w3),kprivate)ECDSA(H(H(H(w_1, w_2),w_4),w_3), k_{private})​

Where ECDSA is the regular elliptic curve digital signature algorithm, HH is the Pedersen hash function, kprivatek_{private} is the user’s private key, and the wordsw1w_1, w2w_2,w3w_3, and w4w_4are 252-bit words containing the data required for the signature, as described in the next section.

Message Word Definition

​w1w_1is the assetId to be sold (or transferred).

​w2w_2depends on the order type:

  • In a Limit Order, w2w_2is the assetId to be bought.

  • In both Transfer and Conditional Transfer, w2w_2is the recipient starkKey.

​w3w_3is 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: order type

    • 0 for a Limit Order

    • 1 for a Transfer

    • 2 for a Conditional Transfer

  • B: vaultId from which the user wants to take funds.

  • C:

    • In case of a limit order, vaultId into which the user wants to receive funds.

    • In case of a Transfer and Conditional Transfer, vaultId to receive the transferred funds.

  • D: quantizedAmount to be sold/transferred.

  • E: quantizedAmount to be bought (0 in case of a Transfer and Conditional Transfer order).

  • F: nonce for the transaction.

  • G: expirationTimestamp, 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βŒŠπ‘‘π‘’π‘›π‘–π‘₯3600βŒ‹+24⌊\frac{𝑑_{𝑒𝑛𝑖π‘₯}}{3600}βŒ‹+24.

​w4w_4 is used only in Conditional Transfer:

  • ​w4w_4 is the condition, which is the keccak of fact and FR_address masked to 250 bits.

keccak(FR_address, fact)) & 0x03FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

where FR_adddress is a contract address and fact is an uint256.

Examples

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

Transfer Example

Suppose that Alice wants to transfer 25 𝑋 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,kstarkKeyBob),m)H(H(100, k_{starkKey}^{Bob}), m)​

Where mm is formatted as follows

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

Conditional Transfer Example

Now Alice wants to do the same transfer but conditional on fact being registered in FR_address . In this case, she will sign the following message:

​H(H(H(100,kstarkKeyBob),condition),m)H(H(H(100, k_{starkKey}^{Bob}),condition), m)​

Where conditioncondition is:

condition = keccak(FR_address, fact))
& 0x03FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

and mm is formatted as follows:

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

Limit Order Example

Suppose that now Alice wants to trade 9000 𝑋 from her vault with ID 7 for 15000 π‘Œ, 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)H(H(100, 200), m)​

Where mm is formatted as follows:

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