Common Objects

class common.objects.api.transaction_requests.TransactionRequest

Transaction

Container for the different transaction types.

Parameters

type (str) – The type of the transaction. For example, “type”: “DepositRequest”.

class common.objects.api.transaction_requests.DepositRequest(vault_id: int, stark_key: int, token_id: int, amount: int)

Deposit transaction.

Parameters

• vault_id (int) – Vault ID in the StarkEx system.

• stark_key (int) – Public key of the party as registered on the StarkEx contract.

• token_id (int) – Unique token ID as registered on the StarkEx contract.

• amount (int) – Amount of token to be deposited; required to be >= 0.

class common.objects.api.transaction_requests.MintRequest(vault_id: int, stark_key: int, token_id: int, amount: int)

Off-chain Mint transaction for ERC-20, ERC-721, and ERC-1155 tokens.

Parameters

• vault_id (int) – The id of the StarkEx vault into which the token is minted.

• stark_key (int) – The public Stark key of the vault owner, as registered on the StarkEx contract.

• token_id (int) – A unique token id. The token must be of a type that is mintable.

• amount (int) – The number of tokens to be minted. This value must be 1 for ERC-721 tokens.

class common.objects.api.transaction_requests.WithdrawalRequest(vault_id: int, stark_key: int, token_id: int, amount: int)

Withdrawal transaction.

Parameters

• vault_id (int) – Vault ID in the StarkEx system.

• stark_key (int) – Public key of the party as registered on the StarkEx contract.

• token_id (int) – Unique token ID as registered on the StarkEx contract.

• amount (int) – Amount of token to be withdrawn; required to be >= 0.

class common.objects.api.transaction_requests.FullWithdrawalRequest(vault_id: int, stark_key: int)

FullWithdrawal transaction.

Parameters

• vault_id (int) – Vault ID in the StarkEx system.

• stark_key (int) – Public key of the party as registered on the StarkEx contract.

class common.objects.api.transaction_requests.FalseFullWithdrawalRequest(vault_id: int, requester_stark_key: int)

FalseFullWithdrawal transaction.

Parameters

• vault_id (int) – Vault ID in the StarkEx system.

• requester_stark_key (int) – stark_key of the (malicious) user that requested the withdrawal.

class common.objects.api.transaction_requests.SettlementRequest(settlement_info: common.objects.api.transaction_requests.SettlementInfoRequest, party_a_order: common.objects.api.transaction_requests.OrderRequest, party_b_order: common.objects.api.transaction_requests.OrderRequest)

The information describing an exchange settlement.

Parameters

• settlement_info (SettlementInfoRequest) – The attributes of the settlement excluding party_a and party_b.

• party_a_order (OrderRequest) – party_a’s order.

• party_b_order (OrderRequest) – party_b’s order.

class common.objects.api.transaction_requests.TransferRequest(amount: int, nonce: int, sender_public_key: int, sender_vault_id: int, token: int, receiver_public_key: int, receiver_vault_id: int, expiration_timestamp: int, signature: services.starkex.gateway.objects.Signature, fee_info_user: Optional[common.objects.api.transaction_requests.FeeInfoUserRequest], fee_info_exchange: Optional[common.objects.api.transaction_requests.FeeInfoExchangeRequest])

The information describing an exchange transfer.

Parameters

• amount (int) – The amount to transfer.

• nonce (int) – The (single) nonce involved in the transfer.

• sender_public_key (int) – The sender’s public key.

• sender_vault_id (int) – The sender’s vault ID.

• token (int) – The token to be transferred.

• receiver_public_key (int) – The receiver’s public key.

• receiver_vault_id (int) – The receiver’s vault ID.

• expiration_timestamp (int) – The expiration time for the transfer, in hours since the Unix epoch (Unix timestamp / 3600).

• signature (Signature) – Signature of the party on the transfer.

• fee_info_user (Optional[FeeInfoUserRequest]) – Fee information given and signed by the user.

• fee_info_exchange (Optional[FeeInfoExchangeRequest]) – Fee information given by the exchange.

signature_message_hash() → int

Computes the transfer object hash.

class common.objects.api.transaction_requests.ConditionalTransferRequest(amount: int, nonce: int, sender_public_key: int, sender_vault_id: int, token: int, receiver_public_key: int, receiver_vault_id: int, expiration_timestamp: int, signature: services.starkex.gateway.objects.Signature, fee_info_user: Optional[common.objects.api.transaction_requests.FeeInfoUserRequest], fee_info_exchange: Optional[common.objects.api.transaction_requests.FeeInfoExchangeRequest], fact_registry_address: str, fact: bytes)

The information describing an exchange conditional transfer.

Parameters

• amount (int) – The amount to transfer.

• nonce (int) – The (single) nonce involved in the transfer.

• sender_public_key (int) – The sender’s public key.

• sender_vault_id (int) – The sender’s vault ID.

• token (int) – The token to be transferred.

• receiver_public_key (int) – The receiver’s public key.

• receiver_vault_id (int) – The receiver’s vault ID.

• expiration_timestamp (int) – The expiration time for the transfer, in hours since the Unix epoch (Unix timestamp / 3600).

• signature (Signature) – Signature of the party on the transfer.

• fact_registry_address (str) – The address of the fact registry smart contract. Should be checksummed according to Web3.isChecksumAddress.

• fact (bytes) – The fact that should appear in the fact registry as a condition to the transfer. A 32 bytes blob.

class common.objects.api.transaction_requests.SettlementInfoRequest(party_a_sold: int, party_b_sold: int, party_a_fee_info: Optional[common.objects.api.transaction_requests.FeeInfoExchangeRequest], party_b_fee_info: Optional[common.objects.api.transaction_requests.FeeInfoExchangeRequest])

The information describing a settlement excluding the parties taking part in it.

Parameters

• party_a_sold (int) – Amount of token A to be transferred from party_a to party_b.

• party_b_sold (int) – Amount of token B to be transferred from party_b to party_a.

• party_a_fee_info (Optional[FeeInfoExchangeRequest]) – The exchange fee info for party a.

• party_b_fee_info (Optional[FeeInfoExchangeRequest]) – The exchange fee info for party b.

class services.starkex.gateway.objects.OrderTypeObsolete(value)

An enumeration.

SETTLEMENT = 0

TRANSFER = 1

class common.objects.api.transaction_requests.OrderRequest(nonce: int, amount_sell: int, amount_buy: int, token_sell: int, token_buy: int, vault_id_sell: int, vault_id_buy: int, expiration_timestamp: int, fee_info: Optional[common.objects.api.transaction_requests.FeeInfoUserRequest])

Can be one of the two:

Parameters

• OrderL2Request (OrderL2Request) – L2 order.

• OrderL1Request (OrderL1Request) – L1 order.

property order_type: Optional[services.starkex.gateway.objects.OrderTypeObsolete]

order_type cannot be defined in OrderRequest since it is a field with a default value and the classes that inherit from OrderRequest have fields without defaults. Defining it in OrderRequest will cause the mypy error Attributes without a default cannot follow attributes with one.

signature_message_hash() → int

Computes the order object hash.

class common.objects.api.transaction_requests.OrderL2Request(nonce: int, amount_sell: int, amount_buy: int, token_sell: int, token_buy: int, vault_id_sell: int, vault_id_buy: int, expiration_timestamp: int, fee_info: Optional[common.objects.api.transaction_requests.FeeInfoUserRequest], public_key: int, signature: services.starkex.gateway.objects.Signature, order_type: Optional[services.starkex.gateway.objects.OrderTypeObsolete] = None)

L2 Order.

Parameters

• nonce (int) – Unique nonce issued by the caller.

• amount_sell (int) – Amount to sell (of token_sell).

• amount_buy (int) – Amount to buy (of token_buy).

• token_sell (int) – Unique ID of the token to sell, as registered on the StarkEx contract.

• token_buy (int) – Unique ID of the token to buy, as registered on the StarkEx contract.

• vault_id_sell (int) – ID of the vault that holds party’s sold token.

• vault_id_buy (int) – ID of the vault that holds party’s bought token.

• expiration_timestamp (int) – The expiration time of the order, in hours since the Unix epoch (Unix timestamp / 3600).

• fee_info (Optional[FeeInfoUserRequest]) – The fee information given by the party.

• public_key (int) – Public key of the party, as registered on the StarkEx contract.

• signature (Signature) – Signature of the party on the order.

• order_type (Optional[OrderTypeObsolete]) – An obsolete order type. Will be deleted in next version. Can be accepted with it or without it.

order_type: Optional[services.starkex.gateway.objects.OrderTypeObsolete] = None

class common.objects.api.transaction_requests.OrderL1Request(nonce: int, amount_sell: int, amount_buy: int, token_sell: int, token_buy: int, vault_id_sell: int, vault_id_buy: int, expiration_timestamp: int, fee_info: common.objects.api.transaction_requests.FeeInfoUserRequest, eth_address: str, order_type: Optional[services.starkex.gateway.objects.OrderTypeObsolete] = None)

L1 Order. An Order that involves only onchain vaults. All vault_ids are limited to 31 bits (as in Validium vaults range) and fee_info is mandatory.

Parameters

• nonce (int) – Unique nonce issued by the caller.

• amount_sell (int) – Amount to sell (of token_sell).

• amount_buy (int) – Amount to buy (of token_buy).

• token_sell (int) – Unique ID of the token to sell, as registered on the StarkEx contract.

• token_buy (int) – Unique ID of the token to buy, as registered on the StarkEx contract.

• vault_id_sell (int) – ID of the vault holding party’s sold token.

• vault_id_buy (int) – ID of the vault holding party’s bought token.

• expiration_timestamp (int) – The expiration timestamp of the order, in hours since the Unix epoch (Unix timstamp / 3600).

• fee_info (FeeInfoUserRequest) – The fee information given by the party.

• eth_address (int) – Ethereum address of the creator of the order.

• order_type (Optional[OrderTypeObsolete]) – An obsolete order type. Will be deleted in next version. Can be accepted with it or without it.

order_type: Optional[services.starkex.gateway.objects.OrderTypeObsolete] = None

class services.starkex.gateway.objects.Signature(r: int, w: Optional[int] = None, s: Optional[int] = None)

Represents a STARK-friendly ECDSA signature.

Parameters

• r (int) – 1st ECDSA signature component. See TBD for further details.

• s (int) – 2nd ECDSA signature component. See TBD for further details.

class common.objects.api.transaction_requests.FeeInfoUserRequest(token_id: int, fee_limit: int, source_vault_id: int)

The Fee information provided and signed by the user: The token ID of the fee, the fee limit, and the ID of the vault from which the fee can be taken. The fee limit is proportional to the user’s signed buy amount - i.e., for every one token_buy received by the party, the fee taken amount is limited to (fee_limit/amount_buy).

Parameters

• token (int) – The fee token.

• fee_limit (int) – The maximum fee to be charged.

• source_vault_id (int) – ID of the vault paying the fee.

class common.objects.api.transaction_requests.FeeInfoExchangeRequest(fee_taken: int, destination_vault_id: int, destination_stark_key: int)

The Fee information provided by the exchange: The actual taken fee amount, the ID of the vault to which the fee will be transferred, and the stark key associated with said vault.

Parameters

• fee_taken (int) – The fee that is actually paid.

• destination_vault_id (int) – ID of the vault receiving the fee.

• destination_stark_key (int) – Stark key of the receiving vault.

class common.objects.transaction.transaction_sign_msg.ValidatedKeylessVaultInfo(vault_id: int, asset_id: int, amount: int)

Asset id, vault id, and amount associated with a StarkEx vault. To identify the vault, the owner key must be known from elsewhere.

Explicitly defines an ordering to allow other hashing implementations to match, and to avoid dependency on a specific library’s version.

Parameters

• asset_id (int) – The token’s identifier.

• vault_id (int) – The vault which holds the token.

• amount (int) – The amount of tokens associated with this vault.

class common.objects.transaction.transaction_sign_msg.ValidatedVaultInfo(vault_id: int, public_key: int, asset_id: int, amount: int)

Owner Key, asset id, vault id, and amount associated with a StarkEx vault.

Explicitly defines an ordering to allow other hashing implementations to match, and to avoid dependency on a specific library’s version.

Parameters

• public_key (int) – The public ID/address of the the vault’s owner.

• asset_id (int) – The token’s identifier.

• vault_id (int) – The vault which holds the token.

• amount (int) – The amount of tokens associated with this vault.

class common.objects.transaction.transaction_sign_msg.FactData(address: str, fact: bytes)

Specification of an onchain fact which must be registered at the specified contract address.

Parameters

• address (str) – The address of the fact registry smart contract. Should be checksummed according to Web3.isChecksumAddress.

• fact (bytes) – The fact that should appear in the fact registry as a condition to the transfer. A 32 bytes blob.

class common.objects.api.transaction_requests.MultiAssetOffchainOrderRequest(nonce: int, expiration_timestamp: int, system_id: int, facts: List[common.objects.transaction.transaction_sign_msg.FactData], give: List[common.objects.transaction.transaction_sign_msg.ValidatedKeylessVaultInfo], receive: List[common.objects.transaction.transaction_sign_msg.ValidatedVaultInfo], public_key: int, signature: services.starkex.gateway.objects.Signature)

A multi-asset order that originates off-chain. This order must be signed, and involve only off-chain vaults.

Parameters

• nonce (int) – A unique nonce issued by the caller.

• expiration_timestamp (int) – The expiration timestamp of the order, in hours since the Unix epoch (Unix timestamp / 3600).

• system_id (int) – A reserved field, must be 0.

• facts (List[FactData]) – A reserved field, must be an empty list.

• give (List[ValidatedKeylessVaultInfo]) – A list of amounts payable from each vault that gives assets in the order. These amounts are the maximum that the sender is willing to pay for each asset in the order.

• receive (List[ValidatedVaultInfo]) – A list of amounts receivable for each vault that receives assets in the order. These amounts are the minimum that the receiver is willing to accept for each asset in the order.

• public_key – The public Stark key of the order’s sender for each specified vault, as registered on the StarkEx contract.

• signature (Signature) – The signature of the order’s sender.

signature_message_hash() → int

Computes the hash of the order object.

class common.objects.api.transaction_requests.MultiAssetFulfillmentInfoRequest(given: List[common.objects.transaction.transaction_sign_msg.ValidatedVaultInfo], received: List[common.objects.transaction.transaction_sign_msg.ValidatedVaultInfo])

A class that represents the actions required to fulfill the orders within a MultiAssetTradeRequest transaction. Reports the net change per vault.

Parameters

• given (List[ValidatedVaultInfo]) – A list of amounts paid from each vault that gives assets in the trade.

• received (List[ValidatedVaultInfo]) – A list of amounts received by each vault that receives assets in the trade.

class common.objects.api.transaction_requests.MultiAssetTradeRequest(orders: List[common.objects.api.transaction_requests.MultiAssetOffchainOrderRequest], fulfillment_info: common.objects.api.transaction_requests.MultiAssetFulfillmentInfoRequest)

A trade of multiple types of assets among multiple parties. Consists of multiple orders, each of which can come from a different party, and their fulfilment information. All orders must be completely fulfilled. Partial fulfillment is not supported.

Parameters

• orders (List[MultiAssetOffchainOrderRequest]) – A list of orders taking part in the trade, each of which includes conditions for receiving and giving assets. To be valid, all receive conditions must be fully met and no give condition can be exceeded.

• fulfillment_info (MultiAssetFulfillmentInfoRequest) – Amounts to receive, that is, withdraw, from the listed vaults in order to complete the trade.

class common.objects.api.transaction_requests.MultiTransactionRequest(txs: List[common.objects.api.transaction_requests.TransactionRequest])

Multi Transaction transaction.

Parameters

txs (List[TransactionRequest]) – The list of transactions.

class services.everest.api.gateway.set_config_request.AlternativeEndpointSettingRequest(url: str, failure_description_url: Optional[str] = None, bearer_token: Optional[str] = None, server_certificate: Optional[str] = None, client_certificate: Optional[str] = None, client_key: Optional[str] = None)

This type of request is allowed only in setups that support dynamically configuring the endpoint for alternative transactions.

AlternativeEndpointSettingRequest is sent from the client to the gateway when the configuration of the alternative transaction request endpoint is changed. The client should provide either of the following: A bearer token, or client and server certificates.

Parameters

• url (str) – The URL of the endpoint.

• failure_description_url (str) – The URL address that receives the failure description.

• bearer_token (Optional[str]) – The Bearer token.

• server_certificate (Optional[str]) – The server certificate.

• client_certificate (Optional[str]) – The client certificate.

• client_key (Optional[str]) – The client private key.