Availability Gateway

class services.perpetual.availability_gateway.availability_gateway.AvailabilityGateway

Perpetual Services HTTP gateway for committee interactions.

async approve_new_roots(request)

Process committee signature for a batch.

Parameters

data – Committee signature data in message body (CommitteeSignature)

Returns

Acknowledgement.

Return type

str

Example

http

POST /availability_gateway/approve_new_roots HTTP/1.1
Host: localhost:9414
Accept: application/json

{"batch_id": 5678, "signature": "0x1256a4d7d152a0aafa2b75eb06eddbd0abb5621572fd4292",
 "member_key": "0xb2849CBc25853685bfc4815Ab51d28E810606A48",
 "claim_hash": "0x476a9f237758279caadaa21ecadd0126fe7ae99eb5c41b7cfdf1f42fd63db577"}

curl

curl -i -X POST https://localhost:9414/availability_gateway/approve_new_roots -H "Accept: application/json" --data-raw '{"batch_id": 5678, "signature": "0x1256a4d7d152a0aafa2b75eb06eddbd0abb5621572fd4292",

 "member_key": "0xb2849CBc25853685bfc4815Ab51d28E810606A48",

 "claim_hash": "0x476a9f237758279caadaa21ecadd0126fe7ae99eb5c41b7cfdf1f42fd63db577"}'

wget

wget -S -O- https://localhost:9414/availability_gateway/approve_new_roots --header="Accept: application/json" --post-data='{"batch_id": 5678, "signature": "0x1256a4d7d152a0aafa2b75eb06eddbd0abb5621572fd4292",

 "member_key": "0xb2849CBc25853685bfc4815Ab51d28E810606A48",

 "claim_hash": "0x476a9f237758279caadaa21ecadd0126fe7ae99eb5c41b7cfdf1f42fd63db577"}'

httpie

echo '{"batch_id": 5678, "signature": "0x1256a4d7d152a0aafa2b75eb06eddbd0abb5621572fd4292",

 "member_key": "0xb2849CBc25853685bfc4815Ab51d28E810606A48",

 "claim_hash": "0x476a9f237758279caadaa21ecadd0126fe7ae99eb5c41b7cfdf1f42fd63db577"}' | http POST https://localhost:9414/availability_gateway/approve_new_roots Accept:application/json

python-requests

requests.post('https://localhost:9414/availability_gateway/approve_new_roots', headers={'Accept': 'application/json'}, data='{"batch_id": 5678, "signature": "0x1256a4d7d152a0aafa2b75eb06eddbd0abb5621572fd4292",\r\n\n "member_key": "0xb2849CBc25853685bfc4815Ab51d28E810606A48",\r\n\n "claim_hash": "0x476a9f237758279caadaa21ecadd0126fe7ae99eb5c41b7cfdf1f42fd63db577"}')

response

HTTP/1.1 200 OK
Content-Type: application/str

signature accepted
async get_batch_data(request)

Get the data availability information for a specific batch.

The availability information includes the ID of the previous batch in chronological order and the list of Merkle leaves (positions and orders) that were modified in the requested batch.

prev_batch_id of -1 indicates that there is no previous state.

Note that prev_batch_id might differ from batch_id - 1. This happens when a previously submitted batch is rejected on-chain.

Parameters

batch_id (int) – Batch ID to query.

Returns

Batch information (StateUpdate)

Example

http

GET /availability_gateway/get_batch_data?batch_id=5678 HTTP/1.1
Host: localhost:9414
Accept: application/json

curl

curl -i -X GET 'https://localhost:9414/availability_gateway/get_batch_data?batch_id=5678' -H "Accept: application/json"

wget

wget -S -O- 'https://localhost:9414/availability_gateway/get_batch_data?batch_id=5678' --header="Accept: application/json"

httpie

http 'https://localhost:9414/availability_gateway/get_batch_data?batch_id=5678' Accept:application/json

python-requests

requests.get('https://localhost:9414/availability_gateway/get_batch_data?batch_id=5678', headers={'Accept': 'application/json'})

response

HTTP/1.1 200 OK
Content-Type: application/json

    {
        "update": {
            "order_root": "000AB5B4CE84EB13D24D4DC89BC96BA10756A91CF180BE92E015F7941D7E",
            "orders": {
                "54850": {
                    "fulfilled_amount": "845"
                },
                "54851": {
                    "fulfilled_amount": "1975"
                }
            },
            "position_root": "037912467B7B3CC02DEEC7B56829E3AE494B8D96F4E79D6CA7CC766C64D1",
            "positions": {
                "168668519": {
                    "assets": {
                        "0x17": {
                            "balance": "64",
                            "cached_funding_index": "16"
                        },
                        "0x37": {
                            "balance": "26",
                            "cached_funding_index": "84"
                        }
                    },
                    "collateral_balance": "88",
                    "public_key": "0xc35327b2be68ae537e02f0d16dd81cf6baac5e02ba28d0342ec8e"
                }
            },
            "prev_batch_id": 5677
        }
    }
async get_blockchain_type(request)

API to query on which blockchain the system is based on: Starknet or Ethereum.

Returns

Type of the blockchain.

async update_signed_batches()

This function scans unsigned batches one by one starting at the BatchSigned offset and checks whether they have enough signatures. For each batch it finds with enough signatures, the function creates a corresponding BatchSigned object. It stops once it finds a batch with insufficient signatures or at the last created batch.

Secondary flow: if an aborted batch is found, the corresponding BatchStateUpdate and BatchSigned are marked as aborted, and the check for sufficient signatures is skipped.

class starkware.starkware_utils.objects.availability.CommitteeSignature

The information describing a committee signature.

Parameters
  • batch_id (int) – ID of signed batch.

  • signature (Union[str, SignatureOverStarknet]) – Committee signature for the batch.

  • member_key (str) – Committee member address used for identification.

  • claim_hash (str) – Claim hash being signed used for validating the expected claim.

class services.perpetual.public.business_logic.state_objects.StateUpdate

The information describing a state update.

Parameters
  • positions (dict) – Dictionary mapping position_id to position state.

  • orders (dict) – Dictionary mapping order_id to order state.

  • position_root (str) – expected position root after update (hex str without prefix).

  • order_root (str) – expected order root after update (hex str without prefix).

  • prev_batch_id (int) – Previous batch ID.

class services.perpetual.public.business_logic.state_objects.PositionState

Position state.

Parameters
  • public_key (int) – Public key of the position’s owner.

  • collateral_balance (int) – The amount of the collateral asset in the position.

  • assets (PositionAsset) – Information on each synthetic asset in the position.

apply_funding(global_funding_indices: services.perpetual.public.business_logic.state_objects.FundingIndicesState)

Computes the total funding for the position and updates the collateral balance accordingly. For each synthetic asset in the position, updates the cached funding index.

static asset_value(asset: services.perpetual.public.business_logic.state_objects.PositionAsset, asset_price: services.perpetual.public.business_logic.state_objects.AssetPrice) starkware.python.fixed_point.FixedPoint

Converts synthetic asset balance to collateral asset balance. Returns a fixed point number with FIXED_POINT_PRECISION precision.

classmethod empty() services.perpetual.public.business_logic.state_objects.PositionState

Returns an empty state object.

property is_empty: bool

Returns true iff the fact represents a leaf that has no value or was deleted.

total_value(asset_prices: Mapping[int, services.perpetual.public.business_logic.state_objects.AssetPrice]) starkware.python.fixed_point.FixedPoint

Calculates the total value of the position. Returns a fixed point number with FIXED_POINT_PRECISION precision.

class services.perpetual.public.business_logic.state_objects.PositionAsset

Position asset.

Parameters
  • balance (int) – Quantized asset amount in the position.

  • cached_funding_index (int) – A snapshot of the funding index at the last time that funding was applied on the position.

class services.perpetual.public.business_logic.state_objects.OrderState

Order state.

Parameters

fulfilled_amount (int) – Order fulfilled amount.

classmethod empty() services.perpetual.public.business_logic.state_objects.OrderState

Returns an empty state object.

property is_empty: bool

Returns true iff the fact represents a leaf that has no value or was deleted.