# Sui ## SDK Sui contracts can program against the [Stork contract's](https://github.com/Stork-Oracle/stork-external/tree/main/contracts/sui) interface by including is as a project dependency. ## Installation {% tabs %} {% tab title="Move" %} 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`: ```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: ```rust // your_module.move use stork::{<...>} ``` {% endtab %} {% endtabs %} ## 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 ```rust 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, // 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`. {% hint style="info" %} 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. {% endhint %} **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`: 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 ```rust public fun update_single_temporal_numeric_value_evm( // stork state object stork_state: &mut StorkState, // the input data update_data: UpdateTemporalNumericValueEvmInput, // fee fee: Coin, // 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`: 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 ```rust public fun update_multiple_temporal_numeric_values_evm( // stork state object stork_state: &mut StorkState, // the input data update_data: UpdateTemporalNumericValueEvmInputVec, // fee fee: Coin, // 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`: 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`](#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`: The [encoded asset ID](https://docs.stork.network/~/changes/suDzkkK15gqdfmjDKr9z/introduction/core-concepts#asset-ids) 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 ```rust 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 ```rust 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 ```rust 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 ```rust 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 ```rust 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 ```rust 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 ```rust public fun update_stork_evm_public_key( _: &AdminCap, state: &mut StorkState, new_stork_evm_public_key: vector, ) ``` **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`: 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 ```rust public fun withdraw_fees( _: &AdminCap, state: &mut StorkState, ctx: &mut TxContext, ): Coin ``` **Description** Withdraws any fees deposited into the `StorkState` as a `Coin`. **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`: The withdrawn fees. **Errors** * `ENoFeesToWithdraw`: If no fees are available to withdraw. This function is version gated and admin gated. ### Migrate ```rust 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 ```rust public fun new( id: vector, temporal_numeric_value_timestamp_ns: u64, temporal_numeric_value_magnitude: u128, temporal_numeric_value_negative: bool, publisher_merkle_root: vector, value_compute_alg_hash: vector, r: vector, s: vector, v: u8, ): UpdateTemporalNumericValueEvmInput ``` **Description** Constructs an object representing an update for a single asset for passing to [`Update Single Temporal Numeric Value EVM`](#update-single-temporal-numeric-value-evm). **Parameters** * `id: vector`: 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`: The publisher's Merkle root. * `value_compute_alg_hash: vector`: Hash of the compute algorithm. * `r: vector`: R component of the signature. * `s: vector`: 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 ```rust public fun new( ids: vector>, temporal_numeric_value_timestamp_nss: vector, temporal_numeric_value_magnitudes: vector, temporal_numeric_value_negatives: vector, publisher_merkle_roots: vector>, value_compute_alg_hashes: vector>, rs: vector>, ss: vector>, vs: vector, ): 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>`: Asset IDs for the updates. * `temporal_numeric_value_timestamp_nss: vector`: Timestamps for the updates. * `temporal_numeric_value_magnitudes: vector`: Magnitudes of the numeric values. * `temporal_numeric_value_negatives: vector`: Indicates whether each value is negative. * `publisher_merkle_roots: vector>`: Publisher Merkle roots. * `value_compute_alg_hashes: vector>`: Hashes of the compute algorithms. * `rs: vector>`: R components of the signatures. * `ss: vector>`: S components of the signatures. * `vs: vector`: 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](https://github.com/Stork-Oracle/stork-external/tree/main/examples/sui).