Forced operations reference

Parameter names that include the term vault refer to a position in StarkEx Perpetual Trading.

Function reference

registerEthAddress

Description

Associates a public Stark key with an Ethereum address.

You can only associate one Ethereum address with a given Stark key pair, although you can associate multiple Stark key pairs with a given Ethereum address.
Parameters
ethKey

The user’s public Ethereum key.
starkKey

The user’s public Stark key.
starkSignature

The user’s Stark signature.
Contract

Users.sol

registerSender

Description

Associates a public Stark key with an Ethereum address. This function serves the same purpose as registerEthAddress, but does not require the ethKey parameter. Instead, this function assigns the account that sends the transaction as the parameter ethKey.

You can only associate one Ethereum address with a given Stark key pair, although you can associate multiple Stark key pairs with a given Ethereum address.
Parameters
starkKey

The user’s public Stark key.
starkSignature

The user’s Stark signature.
Contract

Users.sol

forcedWithdrawalRequest

Description

Withdraws all funds from a position to the on-chain contract, whether the operator services the request or not.

This function ensures users maintain custody of their funds, regardless of the operator’s actions.

Parameters
vaultId

The ID of the position that holds the funds to withdraw.
starkKey

The public Stark key associated with the ID of the position that holds the funds to withdraw and the Ethereum address that initiated the transaction.

If starkKey does not match vaultId, StarkEx proves the invalidity of the request and does not withdraw the funds.

If starkKey does not match the Ethereum address, the StarkEx smart contract rejects the request and the off-chain application does not service the request.
quantizedAmount

The quantized amount to withdraw.
premiumCost

A boolean. When set to true, the transaction is guaranteed to be accepted, but the cost of the transaction is set to 1M gas. When set to false, the cost is lower, but the StarkEx smart contract accepts only ten forcedWithdrawalRequest transactions per block.

premiumCost is the mechanism by which StarkEx prevents denial of service (DoS) attacks, by setting a very high cost for a single forcedWithdrawalRequest transaction.
Contract

ForcedWithdrawals.sol

forcedTradeRequest

Description

Initiates a forced trade request in order to trade with another position.

Because a forced withdrawal transaction can only withdraw collateral, a user must trade all synthetic assets for collateral before initiating a forced withdrawal request, in order to withdraw their account’s full value. For more information, see Forced operations overview.

Before a user can call a forcedTradeRequest function, both parties of the trade must be registered and agree in advance on the terms of the trade.

For information on registering, see the registerEthAddress and registerSender functions.

StarkEx Perpetual Trading v1.0

Registration is not required before submitting a forced trade request.

The party that submits the forced trade request must include the signature of the second party as a parameter.

Parameters
starkKeyA

The public Stark key of party A. This Stark key must be registered with the Ethereum address of the same party.
starkKeyB

The public Stark key of party B. This Stark key must be registered with the Ethereum address of the same party.
vaultIdA

The position ID of party A. This ID must correspond to starkKeyA.
vaultIdB

The position ID of party B. This ID must correspond to starkKeyB.
collateralAssetId

The asset ID of the collateral asset.
syntheticAssetId

The asset ID of the synthetic asset to be sold.
amountCollateral

The amount of collateral to trade, quantized.
amountSynthetic

The amount of the synthetic asset to trade, with resolution applied.
aIsBuyingSynthetic

A boolean. true if party A is buying the synthetic asset. false if party B is buying the synthetic asset.
submissionExpirationTime

The time of the submission, in hours since the Unix epoch. Protects the party that is not submitting the forced trade request from the other party executing the trade at an arbitrary future time.

blockchain_time / 3600 {lteq} submission_expiration_time
nonce

Protects the party that is not submitting the forced trade request against a replay attack.
signature

The signature of the party that is not submitting the forced trade request.
premiumCost

A boolean. When set to true, the transaction is guaranteed to be accepted, but the cost of the transaction is set to 1M gas. When set to false, the cost is lower, but the StarkEx smart contract accepts only ten forcedWithdrawalRequest transactions per block.
Contract

ForcedTrades.sol

freezeRequest

Description

Freezes the exchange, preventing any further state updates. Withdrawals of on-chain funds are still possible.

Any user can call this function if the freeze grace period has passed, and the forced operation is still in the pending forced operations area.

Parameters
vaultId

The same ID used when calling forcedWithdrawalRequest.
starkKey

The same public Stark key used when calling forcedWithdrawalRequest.
Contract

ForcedWithdrawals.sol

verifyEscape

Description

Verifies that the contents of a position belong to a certain Merkle commitment.

For more information, see Escape verifier.

Parameters
merkleProof

The Merkle proof for the position to be evicted.
nAssets

The number of assets in the user’s position.
sharedState

A portion of the application’s state. The user must obtain this from a knowledgable party, such as a data availability provider.
Contract

PerpetualEscapeVerifier.sol

escape

Description

Adds the position balance to an on-chain pending withdrawals account under the public Stark key of the position’s owner and the appropriate asset ID,

If the Escape verifier accepted a proof with the same parameters, and no prior escape call was made for the same position.

Parameters
vaultId

The same ID used when calling forcedWithdrawalRequest.
ownerKey

The same public Stark key used when calling forcedWithdrawalRequest.
quantizedAmount

The quantized amount of the asset being withdrawn.
Contract

PerpetualEscapes.sol

Constant reference

FREEZE_GRACE_PERIOD

Description

The maximum period of time that an operator has to service a forced operation before the user that issued the request can freeze the operator’s smart contract.

Contract

LibConstants.sol

Event reference

LogForcedWithdrawalRequest

Description

Indicates that a user called the forcedWithdrawalRequest function.

Returns
vaultId

The same ID used when calling forcedWithdrawalRequest
starkKey

The same public Stark key used when calling forcedWithdrawalRequest
quantizedAmount

The quantized amount of collateral in the position that the user specifies in the forcedWithdrawRequest transaction.
Contract

ForcedWithdrawals.sol

LogForcedTradeRequest

Description

Indicates that a user called the forcedTradeRequest function.

Returns
starkKeyA

The public Stark key of party A. This Stark key must be registered with the Ethereum address of the same party.
starkKeyB

The public Stark key of party B. This Stark key must be registered with the Ethereum address of the same party.
vaultIdA

The position ID of party A. This ID must correspond to starkKeyA.
vaultIdB

The position ID of party B. This ID must correspond to starkKeyB.
collateralAssetId

The asset ID of the collateral asset.
syntheticAssetId

The asset ID of the synthetic asset to be sold.
amountCollateral

The amount of collateral to trade, quantized.
amountSynthetic

The amount of the synthetic asset to trade, with resolution applied.
aIsBuyingSynthetic

A boolean. true if party A is buying the synthetic asset. false if party B is buying the synthetic asset.
nonce

A unique nonce.

Additional resources