Signature construction
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 with Fees, declaring a regular Limit Order on which the operator can take a fee
-
Conditional Transfer with Fees, declaring a regular Conditional Transfer on which the operator can take a fee
-
Transfer with Fees, declaring a regular Transfer on which the operator can take a fee
-
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/Transfer/Conditional Transfer with Fees, the signature is constructed as follows:
In the case of Limit Order and Transfer, the signature is constructed as follows:
In the case of Conditional Transfer, the signature is constructed as follows:
Where ECDSA is the regular elliptic curve digital signature algorithm, \$H\$ is the Pedersen hash function, \$k_{private}\$ is the user’s private key, and the words \$w_1\$,\$w_2\$,\$w_3\$,\$w_4\$, \$w_5\$ and are 252-bit words containing the data required for the signature, as described in the next section.
Limit Order with Fees
For limit order with fees, the signature is constructed as follows:
\$w_1\$ is the assetId
to be sold
\$w_2\$is the assetId
to be bought.
\$w_3\$is the assetId
used to pay the fee.
\$w_4\$is defined as follows:
+-------+--------------+--------------+--------------+--------+ #bits | 27 | 64 | 64 | 64 | 32 | +-------+--------------+--------------+--------------+--------+ label A B C D E
-
A
: padding of zeros -
B
:quantizedAmount
to be sold. -
C
:quantizedAmount
to be bought -
D
:quantizedAmount
to pay fees -
E
:nonce
for the transaction.
\$w_5\$is defined as follows:
+---+--------------+--------------+--------------+-----+-----+ #bits | 10| 64 | 64 | 64 | 32 | 17 | +---+--------------+--------------+--------------+-----+-----+ label A B C D E F
-
A
: order type-
3 for a Limit Order with Fees
-
-
B
:vaultId
from which the user wants to use to pay fees. -
C
:vaultId
from which the user wants to take the sold asset -
D
:vaultId
from which the user wants to receive the bought asset. -
E
: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: \$⌊\frac{t_{unix}}{3600}⌋+24\$ -
F
: padding of zeros
Transfer/Conditional Transfer with Fees
For Transfer with Fees, the encoding is as follows
For Conditional Transfer with Fees, the encoding is as follows
\$w_1\$is the assetId
to be sold
\$w_2\$is the assetId
used to pay the fee.
\$w_3\$is the receiver_starkKey
used to pay the fee.
\$w_4\$is defined as follows
+-------+--------------+--------------+--------------+--------+ #bits | 27 | 64 | 64 | 64 | 32 | +-------+--------------+--------------+--------------+--------+ label A B C D E
-
A
: padding of zeros -
B
: sendervaultId
-
C
: receivervaultId
-
D
: feevaultId
-
E
:nonce
for the transaction.
\$w_5\$is defined as follows:
+---+--------------+--------------+--------+-----------------+ #bits | 10| 64 | 64 | 32 | 81 | +---+--------------+--------------+--------+-----------------+ label A B C D E
-
A
: order type-
4 for Transfer with Fees
-
5 for Conditional Transfer with Fees
-
-
B
:quantizedAmount
to transfer -
C
:quantizedAmount
to limit the max fee -
D
: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: \$⌊\frac{t_{unix}}{3600}⌋+24\$ -
E
: padding of zeros
\$w_6\$ is the condition
defined as Perdersen hash of the contract address and fact.
Where ECDSA is the regular elliptic curve digital signature algorithm, \$H\$ is the Pedersen hash function, \$k_{private}\$ is the user’s private key, and the words \$w_1\$, \$w_2\$,\$w_3\$, and \$w_4\$are 252-bit words containing the data required for the signature, as described in the next section.
Limit Order/Transfer/Conditional Transfer (deprecated)
In the case of Limit Order and Transfer, the signature is constructed as follows:
In the case of Conditional Transfer, the signature is constructed as follows:
\$w_1\$is the assetId
to be sold (or transferred).
\$w_2\$depends on the order type:
-
In a Limit Order, \$w_2\$is the
assetId
to be bought. -
In both Transfer and Conditional Transfer, \$w_2\$is the recipient
starkKey
.
\$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
: 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: \$⌊\frac{t_{unix}}{3600}⌋+24\$
\$w_4\$ is used only in Conditional Transfer:
-
\$w_4\$ is the
condition
, which is the keccak offact
andFR_address
masked to 250 bits.
keccak(FR_address, fact)) & 0x03FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
where FR_adddress
is a contract address and fact
is an uint256.