GitHubXStork

Sui

Programming API reference for the Stork Sui contract.

SDK

Sui contracts can program against the Stork contract's interface by including is as a project dependency.

Installation

After setting up your Sui Move project, add the Stork contract to your project dependencies by adding the following line to the [dependencies] section of your projects Move.toml:

//Move.toml
[dependencies]
stork = { git = "https://github.com/stork-oracle/stork-external.git", subdir = "contracts/sui/contracts", rev = "main" }

You can now import the Stork interfaces with:

// your_module.move
use stork::{<...>}

Concepts

Version Gating

Some functions, especially if they interact with the StorkState object, are considered "version gated". If the number in the version field if the passed StorkState is not the same as the Version constant in the code, the function will fail will EIncorrectVersion. This can occur when the Stork contract address being used is not pointing to the most recent update of the contract, and is a mechanism to protect against issues that may be present in old versions of the contract. Functions that are not directly version gated, but call version gated functions, are considered version gated.

Admin Gating

Some functions, especially if they mutate the StorkState object, are considered "admin gated". If the caller does not pass in a mutable reference to the AdminCap object created and transferred by the contract upon publishing, or passes but does not own the AdminCap object, the function will fail. Transferring the AdminCap object effectively transfers Admin permissions to the StorkState Object.

stork::stork Methods

Init Stork

entry fun init_stork(
        // admin capability
        _: &AdminCap,
        // the address of the Stork program
        stork_sui_public_key: address,
        // Storks EVM public key
        stork_evm_public_key: vector<u8>,
        // the fee to update a value
        single_update_fee: u64,
        // version of the Stork state 
        stork_state_version: u64,
        // context
        ctx: &mut TxContext,
    )

Description

Creates a new StorkState object and converts it into a publicly shared object. Logs the information in the state, as well as its object ID, in a StorkInitializationEvent.

Given the address of the Stork Contract, the address of the StorkState object can be derived by querying for the Stork Initialization Event, which is always the first event emitted by the Contract.

Parameters

  • _: &AdminCap: A reference to the AdminCap object associated with this contract.

  • stork_sui_public_key: address: The address of the Stork program.

  • stork_evm_public_key: vector<u8>: Stork's EVM public key.

  • single_update_fee: u64: The fee to update a value.

  • stork_state_version: u64: The version of the Stork state.

  • ctx: &mut TxContext: Transaction context.

Behavior

  • This is an entry function and can only be called from off-chain. It cannot take the output of another transaction as input.

  • Fails if the passed state information is invalid.

This function is version gated and admin gated.

Update Single Temporal Numeric Value EVM

public fun update_single_temporal_numeric_value_evm(
        // stork state object
        stork_state: &mut StorkState,
        // the input data
        update_data: UpdateTemporalNumericValueEvmInput,
        // fee
        fee: Coin<SUI>,
        // context
        ctx: &mut TxContext,
    )

Description

Updates the latest value in the relevant feed object based on the provided update data object.

Parameters

  • stork_state: &mut StorkState: A mutable reference to the StorkState object.

  • update_data: UpdateTemporalNumericValueEvmInput: Update data object for a single asset.

  • fee: Coin<SUI>: The fee to pay for the update.

  • ctx: &mut TxContext: Transaction context.

Behavior

  • Verifies the update data's signature using the Stork EVM public key stored on the state object.

  • Verifies that the update is more recent than the data currently in the feed object.

  • If the signature is invalid, the function errors with EInvalidSignature.

  • If the signature is valid but the update is not fresher, the function does not error but does not update the feed object.

  • If both verifications pass, updates the feed object and emits a TemporalNumericValueFeedUpdateEvent

Errors

  • EInvalidSignature: If the signature verification fails.

  • EInsufficientFee: If the fee provided is less than the required amount.

This function is version gated.

Update Multiple Temporal Numeric Values EVM

public fun update_multiple_temporal_numeric_values_evm(
        // stork state object
        stork_state: &mut StorkState,
        // the input data
        update_data: UpdateTemporalNumericValueEvmInputVec,
        // fee
        fee: Coin<SUI>,
        // context
        ctx: &mut TxContext,
    )

Description

Efficiently updates the latest values in multiple feed objects based on the provided update data object.

Parameters

  • stork_state: &mut StorkState: A mutable reference to the StorkState object.

  • update_data: UpdateTemporalNumericValueEvmInputVec: Update data object for multiple assets.

  • fee: Coin<SUI>: The fee to pay for the updates.

  • ctx: &mut TxContext: Transaction context.

Behavior

  • Verifies the signature for each update using the Stork EVM public key.

  • Verifies that each update is fresher than the current feed data.

  • If any signature fails verification, the function errors with EInvalidSignature for all updates.

  • If some updates are not fresher, those specific feed objects are skipped without erroring.

  • Successfully verified and fresher updates are applied to their respective feed objects.

  • Emits a TemporalNumericValueFeedUpdateEvent for each successful update.

Errors

  • EInvalidSignature: If any update's signature verification fails.

  • EInsufficientFee: If the fee provided is less than the required total amount.

This function is more efficient than multiple calls to Update Single Temporal Numeric Value EVM for updating multiple assets.

This function is version gated

Get Temporal Numeric Value Unchecked

public fun get_temporal_numeric_value_unchecked(
    // stork state object
    stork_state: &StorkState,
    // encoded asset id
    feed_id: vector<u8>
    ): TemporalNumericValue

Description

Retrieves the latest value for a specified feed without additional checks.

Parameters

  • stork_state: &StorkState: A reference to the StorkState object.

  • feed_id: vector<u8>: The encoded asset ID of the feed to read.

Returns

  • TemporalNumericValue: The latest value for the relevant feed.

Errors

  • EFeedNotFound: If the specified feed ID does not exist.

This function is version gated.

stork::state Methods

Get Stork EVM Public Key

public fun get_stork_evm_public_key(
    stork_state: &StorkState
    ): EvmPubkey

Description

Retrieves the stored EVM public key from the StorkState.

Parameters

  • stork_state: &StorkState: A reference to the StorkState object.

Returns

  • EvmPubkey: The value of the stork_evm_public_key field of the state.

This function is version gated.

Get Single Update Fee in Mist

public fun get_single_update_fee_in_mist(
    stork_state: &StorkState
    ): u64

Description

Retrieves the fee required to update a single value from the StorkState.

Parameters

  • stork_state: &StorkState: A reference to the StorkState object.

Returns

  • u64: The value of the single_update_fee_in_mist field of the state.

This function is version gated.

Get Stork Sui Address

public fun get_stork_sui_address(
    stork_state: &StorkState
    ): address

Description

Retrieves the stored Sui address of the Stork program from the StorkState.

Parameters

  • stork_state: &StorkState: A reference to the StorkState object.

Returns

  • address: The value of the stork_sui_address field of the state.

This function is version gated.

Get Version

public fun get_version(
    stork_state: &StorkState
    ): u64

Retrieves the version of the StorkState.

Parameters

  • stork_state: &StorkState: A reference to the StorkState object.

Returns

  • u64: The value of the version field of the state.

This function is version gated.

Update Single Update Fee in Mist

public fun update_single_update_fee_in_mist(
        _: &AdminCap,
        state: &mut StorkState,
        new_single_update_fee_in_mist: u64,
    )

Updates the single_update_fee_in_mist field of the StorkState.

Parameters

  • _: &AdminCap: A reference to the AdminCap object.

  • state: &mut StorkState: A mutable reference to the StorkState object.

  • new_single_update_fee_in_mist: u64: The new fee value.

Behavior

  • Updates the single_update_fee_in_mist field of the state.

This function is version gated and admin gated.

Update Stork Sui Address

public fun update_stork_sui_address(
        _: &AdminCap,
        state: &mut StorkState,
        new_stork_sui_address: address,
    )

Description

Updates the stork_sui_address field of the StorkState.

Parameters

  • _: &AdminCap: A reference to the AdminCap object.

  • state: &mut StorkState: A mutable reference to the StorkState object.

  • new_stork_sui_address: address: The new Sui address.

Behavior

  • Updates the stork_sui_address field of the state.

This function is version gated and admin gated.

Update Stork Evm Public Key

public fun update_stork_evm_public_key(
        _: &AdminCap,
        state: &mut StorkState,
        new_stork_evm_public_key: vector<u8>,
    )

Description

Updates the stork_evm_public_key field of the StorkState.

Parameters

  • _: &AdminCap: A reference to the AdminCap object.

  • state: &mut StorkState: A mutable reference to the StorkState object.

  • new_stork_evm_public_key: vector<u8>: The new EVM public key.

Behavior

  • Updates the stork_evm_public_key field of the state.

This function is version gated and admin gated.

Withdraw fees

public fun withdraw_fees(
        _: &AdminCap,
        state: &mut StorkState,
        ctx: &mut TxContext,
  ): Coin<SUI>

Description

Withdraws any fees deposited into the StorkState as a Coin<SUI>.

Parameters

  • _: &AdminCap: A reference to the AdminCap object.

  • state: &mut StorkState: A mutable reference to the StorkState object.

  • ctx: &mut TxContext: Transaction context.

Returns

  • Coin<SUI>: The withdrawn fees.

Errors

  • ENoFeesToWithdraw: If no fees are available to withdraw.

This function is version gated and admin gated.

Migrate

 entry fun migrate(
        _: &AdminCap,
        state: &mut StorkState,
        version: u64,
        stork_sui_address: address,
    )

Description

Migrates the StorkState to a new version and updates the stork_sui_address.

Parameters

  • _: &AdminCap: A reference to the AdminCap object.

  • state: &mut StorkState: A mutable reference to the StorkState object.

  • version: u64: The new version.

  • stork_sui_address: address: The new Sui address.

Behavior

  • Updates the version and stork_sui_address fields of the state.

  • Emits a StorkInitializationEvent.

  • This is an entry function so it can only called from off-chain, and cannot take the ouput of another transaction as an input.

Errors

  • EIncorrectVersion: If the current StorkState version is not the expected version for migration.

When calling this function after upgrading the package, this function should be called on the latest version of the package.

This function is specially version gated, where the StorkState version must equal Version - 1.

stork::temporal_numeric_value_evm_vec Methods

New

public fun new(
        id: vector<u8>,
        temporal_numeric_value_timestamp_ns: u64,
        temporal_numeric_value_magnitude: u128,
        temporal_numeric_value_negative: bool,
        publisher_merkle_root: vector<u8>,
        value_compute_alg_hash: vector<u8>,
        r: vector<u8>,
        s: vector<u8>,
        v: u8,
    ): UpdateTemporalNumericValueEvmInput

Description

Constructs an object representing an update for a single asset for passing to Update Single Temporal Numeric Value EVM.

Parameters

  • id: vector<u8>: The asset ID to update.

  • temporal_numeric_value_timestamp_ns: u64: Timestamp of the temporal numeric value.

  • temporal_numeric_value_magnitude: u128: The magnitude of the numeric value.

  • temporal_numeric_value_negative: bool: Indicates whether the value is negative.

  • publisher_merkle_root: vector<u8>: The publisher's Merkle root.

  • value_compute_alg_hash: vector<u8>: Hash of the compute algorithm.

  • r: vector<u8>: R component of the signature.

  • s: vector<u8>: S component of the signature.

  • v: u8: V component of the signature.

Returns

  • UpdateTemporalNumericValueEvmInput: The constructed update object.

stork::temporal_numeric_value_evm_input Methods

New

public fun new(
        ids: vector<vector<u8>>,
        temporal_numeric_value_timestamp_nss: vector<u64>,
        temporal_numeric_value_magnitudes: vector<u128>,
        temporal_numeric_value_negatives: vector<bool>,
        publisher_merkle_roots: vector<vector<u8>>,
        value_compute_alg_hashes: vector<vector<u8>>,
        rs: vector<vector<u8>>,
        ss: vector<vector<u8>>,
        vs: vector<u8>,
    ): UpdateTemporalNumericValueEvmInputVec

Description

Creates a vector of update objects, each representing an update for a specific asset, where the corresponding update data is keyed by index. For example:

  • ids[i]

  • temporal_numeric_value_timestamp_nss[i]

  • temporal_numeric_value_magnitudes[i]

  • ...

all belong to the same update.

Parameters

  • ids: vector<vector<u8>>: Asset IDs for the updates.

  • temporal_numeric_value_timestamp_nss: vector<u64>: Timestamps for the updates.

  • temporal_numeric_value_magnitudes: vector<u128>: Magnitudes of the numeric values.

  • temporal_numeric_value_negatives: vector<bool>: Indicates whether each value is negative.

  • publisher_merkle_roots: vector<vector<u8>>: Publisher Merkle roots.

  • value_compute_alg_hashes: vector<vector<u8>>: Hashes of the compute algorithms.

  • rs: vector<vector<u8>>: R components of the signatures.

  • ss: vector<vector<u8>>: S components of the signatures.

  • vs: vector<u8>: V components of the signatures.

Behavior

  • Constructs an UpdateTemporalNumericValueEvmInput object for each set of inputs and bundles them into one object.

  • Validates that all input vectors have the same length.

Errors

  • EInvalidLengths: If input vectors do not have the same length.

  • ENoUpdates: If the input vector is empty.

Returns

  • UpdateTemporalNumericValueEvmInputVec: The constructed object containing multiple updates.

Examples

Example usage of the Stork Sui contract can be found in the stork-external github repo.

PreviousSolanaNextChain Pusher Configs

Last updated

#233: Henry / Doc Implementation

Change request updated