Signature construction

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

WithdrawalToAddress

(StarkEx Perpetual v2.0)

Withdrawal to a specific L1 address. Requests collateral to move from the L2 state to L1.

Withdrawal

(StarkEx Perpetual v1.0)

Requests collateral to move from the L2 state to L1.

Liquidate

Limit order with fees, declares intent to sell a certain amount of a certain asset in exchange for a different asset at a certain ratio. One of the assets must be the collateral.

Transfer

Transfer, requests collateral to be transferred from one vault to another.

ConditionalTransfer

Conditional transfer, requests collateral to be transferred from one vault to another if some on-chain event is recorded.

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.

For information on using the corresponding APIs for these transaction types, see Transactions in the StarkEx Perpetual v2.0 REST API reference.

WithdrawalToAddress (StarkEx Perpetual v2.0)

Signature construction

\$ECDSA(H(H(w_1 , w_2), w_3))\$

Where:

ECDSA is the regular elliptic curve digital signature algorithm, \$H\$ is the Pedersen hash function, and \$w_{1-n}\$ are 252-bit words.

Parameters

\$k_{private}\$

The user’s private key

\$w_1\$

The withdrawn assetId

\$w_2\$

The destination L1 address.

\$w_3\$

Defined as follows:

       +----+--------------+----------+--------------+------- --+------------+
#bits  | 10 |      64      |    32    |      64      |    32    |     49     |
       +----+--------------+----------+--------------+------ ---+------------+
label    A         B            C            D             E          F

Where:

A

Order type: 7.

B

positionId from which the user wants to take funds.

C

nonce for the transaction.

D

quantizedAmount to be withdrawn.

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.

Withdrawal (StarkEx Perpetual v1.0 only)

Signature construction

\$ECDSA(H(w_1, w_5), k_{private})\$

Where:

ECDSA is the regular elliptic curve digital signature algorithm, \$H\$ is the Pedersen hash function, and \$w_{1-n}\$ are 252-bit words.

Parameters

\$k_{private}\$

The user’s private key

\$w_1\$

The withdrawn assetId.

\$w_5\$

Defined as follows:

       +----+----------------+---------+---------+---------+------------+
#bits  | 10 |      64        |   32    |    32   |   32   |     49      |
       +----+----------------+---------+---------+---------+------------+
label    A         B             C          D        E          F

Where:

A

Order type: 6.

B

positionId from which the user wants to take funds.

C

nonce for the transaction.

D

quantizedAmount to be withdrawn.

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.

Liquidate (Limit order with fees)

Signature construction

\$ECDSA(H(H(H(H(w_1, w_2), w_3),w_4),w_5), k_{private})\$

Where:

ECDSA is the regular elliptic curve digital signature algorithm, \$H\$ is the Pedersen hash function, and \$w_{1-n}\$ are 252-bit words.

Parameters

\$k_{private}\$

The user’s private key.

\$w_1\$

The assetId to be sold.

\$w_2\$

The assetId to be bought.

\$w_3\$

The assetId used to pay the fee.

\$w_4\$

Defined as follows:

       +-------+--------------+--------------+--------------+--------+
#bits  | 27    |      64      |      64      |      64      |   32   |
       +-------+--------------+--------------+--------------+--------+
label    A            B              C              D           E

Where:

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\$

Defined as follows:

         +---+--------------+--------------+--------------+-----+-----+
#bits    | 10|   64         |   64 .       |         64   | 32  |  17 |
         +---+--------------+--------------+--------------+-----+-----+
label      A      B            C                 D           E     F

Where:

A

Order type: 3.

B

positionId from which the user wants to take funds.

C

positionId from which the user wants to take funds.

D

positionId from which the user wants to take funds.

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

Signature construction

\$ECDSA(H(H(H(H(w_1, w_2), w_3),w_4),w_5), k_{private})\$

Where:

ECDSA is the regular elliptic curve digital signature algorithm, \$H\$ is the Pedersen hash function, and \$w_{1-n}\$ are 252-bit words.

Parameters

\$w_1\$

The assetId to be sold.

\$w_2\$

The assetId used to pay the fee.

\$w_3\$

The receiver_starkKey used to pay the fee.

\$w_4\$

Defined as follows:

         +-------+--------------+--------------+--------------+--------+
#bits    | 27    |   64         |   64 .       |      64      |   32   |
         +-------+--------------+--------------+--------------+--------+
label      A               B            C                 D       E

Where:

A

Padding of zeros.

B

Sender’s positionId.

C

Receiver’s positionId.

D

Fee positionId.

E

nonce for the transaction.

\$w_5\$

Defined as follows:

         +---+--------------+--------------+--------+-----------------+
#bits    | 10|   64         |   64         |   32   |       81        |
         +---+--------------+--------------+--------+-----------------+
label      A      B            C                 D           E

Where:

A

Order type: 4.

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.

ConditionalTransfer

Signature construction

\$ECDSA(H(H(H(H(H(w_1, w_2), w_3),w_6),w_4),w_5), k_{private})\$

Where:

ECDSA is the regular elliptic curve digital signature algorithm, \$H\$ is the Pedersen hash function, and \$w_{1-n}\$ are 252-bit words.

Parameters

\$w_1\$

The assetId to be sold.

\$w_2\$

The assetId used to pay the fee.

\$w_3\$

The receiver_starkKey used to pay the fee.

\$w_4\$

Defined as follows:

         +-------+--------------+--------------+--------------+--------+
#bits    | 27    |   64         |   64 .       |      64      |   32   |
         +-------+--------------+--------------+--------------+--------+
label      A               B            C                 D       E

Where:

A

Padding of zeros.

B

Sender’s positionId.

C

Receiver’s positionId.

D

Fee positionId.

E

nonce for the transaction.

\$w_5\$

Defined as follows:

         +---+--------------+--------------+--------+-----------------+
#bits    | 10|   64         |   64         |   32   |       81        |
         +---+--------------+--------------+--------+-----------------+
label      A      B            C                 D           E

Where:

A

Order type: 5.

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.