Availability Gateway

class services.starkex.availability_gateway.availability_gateway.AvailabilityGateway(general_config: services.starkex.definitions.general_config.StarkexGeneralConfig, availability_gateway_config: services.starkex.availability_gateway.availability_gateway_config.AvailabilityGatewayConfig, storage: starkware.storage.storage.Storage, lock_manager: starkware.storage.storage.LockManager, hash_func)

This is the StarkEx 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: aiohttp.web_request.Request) → aiohttp.web_response.Response

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 tree leaves (validium vaults tree and orders tree) that were modified in the requested batch.

If validate_rollup is set to True, the list of rollup vault tree leaves that were modified is also returned. 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.

  • validate_rollup (bool) – Boolean string (either “True” or “False”) indicating whether or not to respond with rollup vault modification data.

Returns

Batch information (StateUpdate)

Example

http

GET /availability_gateway/get_batch_data?batch_id=5678&validate_rollup=True 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&validate_rollup=True' -H "Accept: application/json"

wget

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

httpie

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

python-requests

requests.get('https://localhost:9414/availability_gateway/get_batch_data?batch_id=5678&validate_rollup=True', 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"
                }
            },
            "prev_batch_id": 5677,
            "rollup_vault_root": "DEADBEEF",
            "rollup_vaults": {
                "9223372037023444327": {
                    "balance": "9",
                    "stark_key": "0x1234",
                    "token": "0x5678"
                }
            },
            "vault_root": "037912467B7B3CC02DEEC7B56829E3AE494B8D96F4E79D6CA7CC766C64D1",
            "vaults": {
                "168668519": {
                    "balance": "300",
                    "stark_key": "0xc35327b2be68ae537e02f0d16dd81cf6baac5e02ba28d0342ec8e",
                    "token": "0x31e95e8dc9447dfb706f0dfa2d8243c832de7d8da4edd87aa8f3f0008"
                },
                "694774812": {
                    "balance": "1000",
                    "stark_key": "0x7c5a4b3c65e46bc7b7b1e5dce60b5b5c56d9429f27acf53ec45b9",
                    "token": "0x31e95e8dc9447dfb706f0dfa2d8243c832de7d8da4edd87aa8f3f0008"
                }
            }
        }
    }
async init_dummy_batch_state_update_with_rollup()

Initializes default StateUpdate object (needed in case of aborted batches). The dummy batch is a fixed batch that committee can process and approve in minimal time. It contains 0 transactions, and it relies on ‘batch -1’ (roots of empty vaults / rollup vaults / orders trees). Differs from init_dummy_batch_state_update_without_rollup in that a new state object is initialized, not the old version.

async init_dummy_batch_state_update_without_rollup()

Initializes default StateUpdate object (needed in case of aborted batches). The dummy batch is a fixed batch that committee can process and approve in minimal time. It contains 0 transactions, and it relies on ‘batch -1’ (roots of empty vaults / orders trees).

async order_tree_height(request)

API to query the height of the order tree.

Returns

Height of the order tree.

class starkware.starkware_utils.objects.availability.CommitteeSignature(batch_id: int, signature: str, member_key: str, claim_hash: str)

The information describing a committee signature.

Parameters

  • batch_id (int) – ID of signed batch.

  • signature (str) – Committee signature for batch.

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

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

class starkware.starkware_utils.objects.starkex_state.StateUpdateVersion1(prev_batch_id: int, vaults: Dict[int, starkware.starkware_utils.objects.starkex_state.VaultState], orders: Dict[int, starkware.starkware_utils.objects.starkex_state.OrderState], vault_root: str, order_root: str)
class starkware.starkware_utils.objects.starkex_state.StateUpdateVersion2(prev_batch_id: int, vaults: Dict[int, starkware.starkware_utils.objects.starkex_state.VaultState], orders: Dict[int, starkware.starkware_utils.objects.starkex_state.OrderState], vault_root: str, order_root: str, rollup_vaults: Dict[int, starkware.starkware_utils.objects.starkex_state.VaultState], rollup_vault_root: str)

The information describing a state update with volition. Includes both validium and rollup updates and tree roots; validium updates/root is still referred to as ‘vaults’/’vault_root’ for backwards compatability.

Parameters

  • rollup_vaults (dict) – Dictionary mapping vault_id to vault state.

  • rollup_vault_root (str) – expected rollup vault root after update (hex str without prefix).

starkware.starkware_utils.objects.starkex_state.StateUpdate

alias of starkware.starkware_utils.objects.starkex_state.StateUpdateVersion2

class starkware.starkware_utils.objects.starkex_state.VaultState(stark_key: int, token: int, balance: int)

Vault state.

Parameters

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

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

  • balance (int) – Vault balance.

classmethod empty() → starkware.starkware_utils.objects.starkex_state.VaultState

Returns an empty state object.

property is_empty: bool

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

class starkware.starkware_utils.objects.starkex_state.OrderState(fulfilled_amount: int)

A leaf of the orders tree. May represent either the fulfillment state of an order or the minted state of a mintable asset.

Parameters

fulfilled_amount (int) – If the leaf represents an order, this is the amount fulfilled; if the leaf represents a mintable asset, this is the amount minted.

classmethod empty() → starkware.starkware_utils.objects.starkex_state.OrderState

Returns a state object representing a 0 fulfilled order or an unminted mintable asset.

property is_empty: bool

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