Comment on page
Settlement (Trading)
Learn how to execute settlements in your Arc application.
The settlement operation allows for the trade of assets between two users. The action can be executed via a single API call, with support for all assets enabled in your application. The details, from both users, must be signed and subsequently submitted by your application to Arc.
The following steps illustrate the typical flow of a settlement operation in Arc:
- 1.Application has two users that want to settle assets. For each user, the Application needs to compute a signable payload.
- 2.Each user signs their settlement order based on the signable payload and submits a POST request to Application's endpoint to execute the settlement.
- 3.The Application receives the settlement request from the users and forwards it to the /api/v1/settlements endpoint of the Arc API.
- 4.Arc receives the settlement request from the application, performs validation actions, and if the validation passes, updates the balances for the users involved in the settlement.
- 5.The Application then sends a response back to the users indicating that the settlement was successful.
To generate the required settlement signature for each user, first you need to get the messageHash that the users need to sign with their private STARK key. In order to do this, you can use StarkEx JS crypto SDK, our own SDK in C#.
Typescript
C#
Python
// init cryptoUtils
const cryptoUtils: ICryptoUtils = new CryptoUtils();
await cryptoUtils.init(message);
// order data
const orderData: OrderDataDto = {
sellQuantizedAmount: '21415926535',
buyQuantizedAmount: '1',
sellVaultChainId: 1,
buyVaultChainId: 2,
expirationTimestamp: 123123123,
nonce: 123,
assetBuy: '0x123abcafff',
assetSell: '0x123abca123',
};
var transferMessage = new EncodeLimitOrderWithFeesModel
{
AssetIdSold = sellVault.AssetStarkExId,
AssetIdBought = buyVault.AssetStarkExId,
AssetIdUsedForFees = feesVault.AssetStarkExId,
QuantizedAmountSold = sellAmountQuantized,
QuantizedAmountBought = buyAmountQuantized,
QuantizedAmountUsedForFees = feeAmountQuantized,
Nonce = nonce,
VaultIdUsedForFees = feesVault.VaultChainId,
VaultIdUsedForSelling = sellVault.VaultChainId,
VaultIdUsedForBuying = buyVault.VaultChainId,
ExpirationTimestamp = expirationTimestamp,
};
var messageHash = target.EncodeLimitOrderWithFees(transferMessage);
# Signing payload hash with StarkWare's Python resources
# https://github.com/starkware-libs/starkex-resources/blob/master/crypto/starkware/crypto/signature/starkex_messages.py
from .signature import FIELD_PRIME, pedersen_hash
def get_limit_order_msg(
vault_sell: int, vault_buy: int, amount_sell: int, amount_buy: int, token_sell: int,
token_buy: int, nonce: int, expiration_timestamp: int,
hash=pedersen_hash) -> int:
"""
party_a sells amount_sell coins of token_sell from vault_sell.
party_a buys amount_buy coins of token_buy into vault_buy.
"""
assert 0 <= vault_sell < 2**31
assert 0 <= vault_buy < 2**31
assert 0 <= amount_sell < 2**63
assert 0 <= amount_buy < 2**63
assert 0 <= token_sell < FIELD_PRIME
assert 0 <= token_buy < FIELD_PRIME
assert 0 <= nonce < 2**31
assert 0 <= expiration_timestamp < 2**22
instruction_type = 0
return get_msg(
instruction_type, vault_sell, vault_buy, amount_sell, amount_buy, token_sell, token_buy,
nonce, expiration_timestamp, hash=hash)
To generate the required signature, asked in the first form under /api/v1/settlements, users should sign the
signablePayload with their private STARK key. In order to do this, you can use StarkEx JS crypto SDK, our own SDK in C#.Typescript
C#
Python
const signature = cryptoUtils.settlements().signOrder(orderData);
var messageHash = "5359c71cf08f394b7eb713532f1a0fcf1dccdf1836b10db2813e6ff6b6548db"
var privateKey = "2dccce1da22003777062ee0870e9881b460a8b7eca276870f57c601f182136c";
var signer = CreateStarkExSigner();
// R: "5f496f6f210b5810b2711c74c15c05244dad43d18ecbbdbe6ed55584bc3b0a2",
// S: "4e8657b153787f741a67c0666bad6426c3741b478c8eaa3155196fc571416f3"
var signature = signer.SignMessage(messageHash, privateKey);
# Signing payload hash with StarkWare's Python resources
# https://github.com/starkware-libs/starkex-resources/blob/master/crypto/starkware/crypto/signature/signature_test.py
from .signature import sign
r, s = sign(transfer_msg, private_key)
To settle assets between two users, applications can issue an HTTP POST request /api/v1/settlements with the following body:
post
https://testnet-api.onarc.io
/api/v1/settlements
Submit Settlement
Last modified 2mo ago