Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update host function interface to the latest env #1415

Merged
merged 1 commit into from
Oct 26, 2023
Merged

Update host function interface to the latest env #1415

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
63 changes: 25 additions & 38 deletions core/cap-0046-03.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,9 +52,6 @@ With that, we now present the host functions.
;; Emit a diagnostic event containing a message and sequence of `Val`s.
(func $log_from_linear_memory (param $msg_pos_u32_val i64) (param $msg_len_u32_val i64) (param $vals_pos_u32_val i64) (param $vals_len_u32_val i64) (result i64))

;; Get the address object of the contract which invoked the running contract. Traps if the running contract was not invoked by a contract.
(func $get_invoking_contract (result i64))

;; Compare two objects, or at least one object to a non-object, structurally. Returns -1 if a<b, 1 if a>b, or 0 if a==b.
(func $obj_cmp (param $a_val i64) (param $b_val i64) (result i64))

Expand All @@ -70,9 +67,6 @@ With that, we now present the host functions.
;; Return the timestamp number of the current ledger as a u64.
(func $get_ledger_timestamp (result u64))

;; Returns the full call stack from the first contract call to the current one as a vector of vectors, where the inside vector contains the contract id as Hash, and a function as a Symbol.
(func $get_current_call_stack (result i64))

;; Causes the currently executing contract to fail immediately with a provided error code, which must be of error-type `ScErrorType::Contract`. Does not actually return.
(func $fail_with_error (param $error_error i64) (result i64))

Expand Down Expand Up @@ -172,6 +166,9 @@ With that, we now present the host functions.
;; Performs checked integer division. Computes `lhs / rhs`, returning `ScError` if `rhs == 0` or overflow occurred.
(func $u256_div (param $lhs_u256_val i64) (param $rhs_u256_val i64) (result i64))

;; Performs checked Euclidean modulo. Computes `lhs % rhs`, returning `ScError` if `rhs == 0` or overflow occurred.
(func $u256_rem_euclid (param $lhs_u256_val i64) (param $rhs_u256_val i64) (result i64))

;; Performs checked exponentiation. Computes `lhs.exp(rhs)`, returning `ScError` if overflow occurred.
(func $u256_pow (param $lhs_u256_val i64) (param $rhs_u32_val i32) (result i64))

Expand All @@ -193,6 +190,9 @@ With that, we now present the host functions.
;; Performs checked integer division. Computes `lhs / rhs`, returning `ScError` if `rhs == 0` or overflow occurred.
(func $i256_div (param $lhs_i256_val i64) (param $rhs_i256_val i64) (result i64))

;; Performs checked Euclidean modulo. Computes `lhs % rhs`, returning `ScError` if `rhs == 0` or overflow occurred.
(func $i256_rem_euclid (param $lhs_i256_val i64) (param $rhs_i256_val i64) (result i64))

;; Performs checked exponentiation. Computes `lhs.exp(rhs)`, returning `ScError` if overflow occurred.
(func $i256_pow (param $lhs_i256_val i64) (param $rhs_u32_val i32) (result i64))

Expand Down Expand Up @@ -236,17 +236,11 @@ With that, we now present the host functions.
;; Test for the presence of a key in a map. Returns Bool.
(func $map_has (param $m_map_object i64) (param $k_val i64) (result i64))

;; Given a key, find the first key less than itself in the map's sorted order. If such a key does not exist, return an ScError.
(func $map_prev_key (param $m_map_object i64) (param $k_val i64) (result i64))
;; Get the key from a map at position `i`. If `i` is an invalid position, return ScError.
(func $map_key_by_pos (param $m_map_object i64) (param $i_u32_val i64) (result i64))

;; Given a key, find the first key greater than itself in the map's sorted order. If such a key does not exist, return an ScError.
(func $map_next_key (param $m_map_object i64) (param $k_val i64) (result i64))

;; Find the minimum key from a map. If the map is empty, return an ScError.
(func $map_min_key (param $m_map_object i64) (result i64))

;; Find the maximum key from a map. If the map is empty, return an ScError.
(func $map_max_key (param $m_map_object i64) (result i64))
;; Get the value from a map at position `i`. If `i` is an invalid position, return ScError.
(func $map_val_by_pos (param $m_map_object i64) (param $i_u32_val i64) (result i64))

;; Return a new vector containing all the keys in a map. The new vector is ordered in the original map's key-sorted order.
(func $map_keys (param $m_map_object i64) (result i64))
Expand All @@ -263,8 +257,8 @@ With that, we now present the host functions.

### "Vec" host functions (mod `v`)
```
;; Creates a new vector with an optional capacity hint `c`. If `c` is `Void`, no hint is assumed and the new vector is empty. Otherwise, `c` is parsed as a `u32` that represents the initial capacity of the new vector.
(func $vec_new (param $c_val i64) (result i64))
;; Creates an empty new vector.
(func $vec_new () (result i64))

;; Update the value at index `i` in the vector. Return the new vector. Trap if the index is out of bounds.
(func $vec_put (param $v_vec_object i64) (param $i_u32_val i64) (param $x_val i64) (result i64))
Expand Down Expand Up @@ -311,7 +305,7 @@ With that, we now present the host functions.
;; Get the index of the last occurrence of a given element in the vector. Returns the u32 index of the value if it's there. Otherwise, it returns `Void`.
(func $vec_last_index_of (param $v_vec_object i64) (param $x_val i64) (result i64))

;; Binary search a sorted vector for a given element. If it exists, the high-32 bits of the return value is 0x0001 and the low-32 bits contain the u32 index of the element. If it does not exist, the high-32 bits of the return value is 0x0000 and the low-32 bits contain the u32 index at which the element would need to be inserted into the vector to maintain sorted order.
;; Binary search a sorted vector for a given element. If it exists, the high-32 bits of the return value is 0x0001 and the low-32 bits contain the u32 index of the element. If it does not exist, the high-32 bits of the return value is 0x0000_0001 and the low-32 bits contain the u32 index at which the element would need to be inserted into the vector to maintain sorted order.
(func $vec_binary_search (param $v_vec_object i64) (param $x_val i64) (result u64))

;; Return a new vec initialized from an input slice of Vals given by a linear-memory address and length.
Expand All @@ -324,8 +318,7 @@ With that, we now present the host functions.

### "Ledger" host functions (mod `l`)
```
;; If `f` is `Void`, then there will be no changes to flags for an existing entry, and none will be set if this is a new entry. Otherwise, `f` is parsed as a `u32`. If the value is 0, then all flags are cleared. If it's not 0, then flags will be set to the passed in value.
(func $put_contract_data (param $k_val i64) (param $v_val i64) (param $t_storage_type i64) (param $f_val i64) (result i64))
(func $put_contract_data (param $k_val i64) (param $v_val i64) (param $t_storage_type i64) (result i64))

(func $has_contract_data (param $k_val i64) (param $t_storage_type i64) (result i64))

Expand All @@ -345,14 +338,14 @@ With that, we now present the host functions.
;; Replaces the executable of the current contract with the provided Wasm code identified by a hash. Wasm entry corresponding to the hash has to already be present in the ledger. The update happens only after the current contract invocation has successfully finished, so this can be safely called in the middle of a function.
(func $update_current_contract_wasm (param $hash_bytes_object i64) (result i64))

;; If the entry's TTL is below `threshold` ledgers, extend `live_until_ledger_seq` such that TTL == `extend_to`, where TTL is defined as `live_until_ledger_seq - current ledger`.
(func $extend_contract_data (param $k_val i64) (param $t_storage_type i64) (param $threshold_val u64) (param $extend_to_val u64) (result i64))
;; If the entry's TTL is below `threshold` ledgers, extend `live_until_ledger_seq` such that TTL == `extend_to`, where TTL is defined as live_until_ledger_seq - current ledger.
(func $extend_contract_data (param $k_val i64) (param $t_storage_type i64) (param $threshold_u32_val i64) (param $extend_to_u32_val i64) (result i64))

;; If the TTL for the current contract instance and code (if applicable) is below `threshold` ledgers, extend `live_until_ledger_seq` such that TTL == `extend_to`, where TTL is defined as `live_until_ledger_seq - current ledger`.
(func $extend_current_contract_instance_and_code (param $threshold_val u64) (param $extend_to_val u64) (result i64))
;; If the TTL for the current contract instance and code (if applicable) is below `threshold` ledgers, extend `live_until_ledger_seq` such that TTL == `extend_to`, where TTL is defined as live_until_ledger_seq - current ledger.
(func $extend_current_contract_instance_and_code (param $threshold_u32_val i64) (param $extend_to_u32_val i64) (result i64))

;; If the TTL for the provided contract instance and code (if applicable) is below `threshold` ledgers, extend `live_until_ledger_seq` such that TTL == `extend_to`, where TTL is defined as `live_until_ledger_seq - current ledger`.
(func $extend_contract_instance_and_code (param $contract_address_object i64) (param $threshold_val u64) (param $extend_to_val u64) (result i64))
;; If the TTL for the provided contract instance and code (if applicable) is below `threshold` ledgers, extend `live_until_ledger_seq` such that TTL == `extend_to`, where TTL is defined as live_until_ledger_seq - current ledger.
(func $extend_contract_instance_and_code (param $contract_address_object i64) (param $threshold_u32_val i64) (param $extend_to_u32_val i64) (result i64))

;; Get the id of a contract without creating it. `deployer` is address of the contract deployer. `salt` is used to create a unique contract id. Returns the address of the would-be contract.
(func $get_contract_id (param $deployer_address_object i64) (param $salt_bytes_object i64) (result i64))
Expand All @@ -367,7 +360,7 @@ With that, we now present the host functions.
;; Calls a function in another contract with arguments contained in vector `args`. If the call is successful, returns the result of the called function. Traps otherwise.
(func $call (param $contract_address_object i64) (param $func_symbol i64) (param $args_vec_object i64) (result i64))

;; Calls a function in another contract with arguments contained in vector `args`, returning either the result of the called function or an ScError if the called function failed.
;; Calls a function in another contract with arguments contained in vector `args`, returning either the result of the called function or an `Error` if the called function failed. The returned error is either a custom `ContractError` that the called contract returns explicitly, or an error with type `Context` and code `InvalidAction` in case of any other error in the called contract (such as a host function failure that caused a trap). `try_call` might trap in a few scenarios where the error can't be meaningfully recovered from, such as running out of budget.
(func $try_call (param $contract_address_object i64) (param $func_symbol i64) (param $args_vec_object i64) (result i64))

```
Expand Down Expand Up @@ -470,17 +463,11 @@ With that, we now present the host functions.
;; Checks if the address has authorized the invocation of the current contract function with all the arguments of the invocation. Traps if the invocation hasn't been authorized.
(func $require_auth (param $address_address_object i64) (result i64))

;; Converts a provided 32-byte Stellar account public key to the corresponding address. This is only useful in the context of cross-chain interoperability. Prefer directly using the Address objects whenever possible.
(func $account_public_key_to_address (param $pk_bytes_bytes_object i64) (result i64))

;; Converts a provided 32-byte contract identifier to a corresponding Address object.
(func $contract_id_to_address (param $contract_id_bytes_bytes_object i64) (result i64))

;; Returns the 32-byte public key of the Stellar account corresponding to the provided Address object. If the Address doesn't belong to an account, returns Val corresponding to the unit type (`()`).
(func $address_to_account_public_key (param $address_address_object i64) (result i64))
;; Converts a provided Stellar strkey address of an account or a contract ('G...' or 'C...' respectively) to an address object. `strkey` can be either `BytesObject` or `StringObject` (the contents should represent the `G.../C...` string in both cases). Any other valid or invalid strkey (e.g. 'S...') will trigger an error. Prefer directly using the Address objects whenever possible. This is only useful in the context of custom messaging protocols (e.g. cross-chain).
(func $strkey_to_address (param $strkey_val i64) (result i64))

;; Returns the 32-byte contract identifier corresponding to the provided Address object. If the Address doesn't belong to an account, returns Val corresponding to the unit type (`()`).
(func $address_to_contract_id (param $address_address_object i64) (result i64))
;; Converts a provided address to Stellar strkey format ('G...' for account or 'C...' for contract). Prefer directly using the Address objects whenever possible. This is only useful in the context of custom messaging protocols (e.g. cross-chain).
(func $address_to_strkey (param $address_address_object i64) (result i64))

;; Authorizes sub-contract calls for the next contract call on behalf of the current contract. Every entry in the argument vector corresponds to `InvokerContractAuthEntry` contract type that authorizes a tree of `require_auth` calls on behalf of the current contract. The entries must not contain any authorizations for the direct contract call, i.e. if current contract needs to call contract function F1 that calls function F2 both of which require auth, only F2 should be present in `auth_entries`.
(func $authorize_as_curr_contract (param $auth_entires_vec_object i64) (result i64))
Expand Down
Loading