From 3a7e0fd8e663fcb039fb413137c3ca5094183041 Mon Sep 17 00:00:00 2001 From: Victor Camacho Date: Tue, 15 Sep 2020 16:47:11 -0400 Subject: [PATCH 01/14] document some host functions --- .../eosio/chain/webassembly/interface.hpp | 1267 +++++++++++++++-- libraries/chain/webassembly/privileged.cpp | 9 - 2 files changed, 1167 insertions(+), 109 deletions(-) diff --git a/libraries/chain/include/eosio/chain/webassembly/interface.hpp b/libraries/chain/include/eosio/chain/webassembly/interface.hpp index d1f854e771b..7471b8b0f61 100644 --- a/libraries/chain/include/eosio/chain/webassembly/interface.hpp +++ b/libraries/chain/include/eosio/chain/webassembly/interface.hpp @@ -16,28 +16,277 @@ namespace webassembly { inline apply_context& get_context() { return context; } inline const apply_context& get_context() const { return context; } - // context free api + /** + * Retrieve the signed_transaction.context_free_data[index]. + * + * @ingroup context-free + * @param index - the index of the context_free_data entry to retrieve. + * @param[out] buffer - output buffer of the context_free_data entry. + * + * @retval -1 if the index is not valid + * @retval size of the cfd if the buffer is empty, otherwise return the amount of data copied onto the buffer. + */ int32_t get_context_free_data(uint32_t index, legacy_span buffer) const; - // privileged api + /** + * Check if a feature is found on the activation set. + * + * @ingroup privileged + * @param feature_name - 256-bit digest representing the feature to query. + * + * @return false (deprecated) + * + * @deprecated + */ int32_t is_feature_active(int64_t feature_name) const; + + /** + * Activate a a consensus protocol upgrade. + * + * @ingroup privileged + * @param feature_name - 256-bit digest representing the feature to activate. + * + * @deprecated + */ void activate_feature(int64_t feature_name) const; - void preactivate_feature(legacy_ptr); + + /** + * Allows a privileged smart contract, e.g. the system contract, to pre-activate a consensus protocol upgrade feature. + * + * @ingroup privileged + * @param digest_type - 256-bit digest representing the feature to pre-activate. + */ + void preactivate_feature(legacy_ptr feature_digest); + + /* + * Set the resource limits of an account. + * + * @ingroup privileged + * + * @param account - name of the account whose resource limit to be set. + * @param ram_bytes -ram limit in absolute bytes. + * @param net_weight - fractionally proportionate net limit of available resources based on (weight / total_weight_of_all_accounts). + * @param cpu_weight - fractionally proportionate cpu limit of available resources based on (weight / total_weight_of_all_accounts). + */ void set_resource_limits(account_name account, int64_t ram_bytes, int64_t net_weight, int64_t cpu_weight); + + /* + * Get the resource limits of an account + * + * @ingroup privileged + * + * @param account - name of the account whose resource limit to get. + * @param[out] ram_bytes - output to hold retrieved ram limit in absolute bytes. + * @param[out] net_weight - output to hold net weight. + * @param[out] cpu_weight - output to hold cpu weight. + */ void get_resource_limits(account_name account, legacy_ptr ram_bytes, legacy_ptr net_weight, legacy_ptr cpu_weight) const; - void set_resource_limit(account_name, name, int64_t); + + /** + * Get the current wasm limits configuration. + * + * The structure of the parameters is as follows: + * + * - max_mutable_global_bytes + * The maximum total size (in bytes) used for mutable globals. + * i32 and f32 consume 4 bytes and i64 and f64 consume 8 bytes. + * Const globals are not included in this count. + * + * - max_table_elements + * The maximum number of elements of a table. + * + * - max_section_elements + * The maximum number of elements in each section. + * + * - max_linear_memory_init + * The size (in bytes) of the range of memory that may be initialized. + * Data segments may use the range [0, max_linear_memory_init). + * + * - max_func_local_bytes + * The maximum total size (in bytes) used by parameters and local variables in a function. + * + * - max_nested_structures + * The maximum nesting depth of structured control instructions. + * The function itself is included in this count. + * + * - max_symbol_bytes + * The maximum size (in bytes) of names used for import and export. + * + * - max_module_bytes + * The maximum total size (in bytes) of a wasm module. + * + * - max_code_bytes + * The maximum size (in bytes) of each function body. + * + * - max_pages + * The maximum number of 64 KiB pages of linear memory that a contract can use. + * Enforced when an action is executed. The initial size of linear memory is also checked at setcode. + * + * - max_call_depth + * The maximum number of functions that may be on the stack. Enforced when an action is executed. + * + * @ingroup privileged + * + * @param[out] packed_parameters the ouput for the parameters. + * @param max_version has no effect, but should be 0. + * + * @retval the size of the packed parameters if packed_parameters is empty. + * @retval the amount of data written in packed_parameters. + */ uint32_t get_wasm_parameters_packed( span packed_parameters, uint32_t max_version ) const; + + /** + * Set the configuration for wasm limits. + * + * See get_wasm_parameters_packed documentation for more details on the structure of the packed_parameters. + * + * @ingroup privileged + * + * @param packed_parameters - a span containing the packed configuration to set. + */ void set_wasm_parameters_packed( span packed_parameters ); - int64_t get_resource_limit(account_name, name) const; + + /** + * Update a single resource limit associated with an account. + * + * @ingroup privileged + * + * @param account - the account whose limits are being modified. + * @param resource - the resource to update, which should be either ram, cpu, or net. + * @param limit - the new limit. A value of -1 means unlimited. + * + * @pre limit >= -1 + */ + void set_resource_limit(account_name account, name resource, int64_t limit); + + /** + * Get a single resource limit associated with an account. + * + * @ingroup privileged + * + * @param account - the account whose limits are being modified + * @param resource - the name of the resource limit which should be either ram, cpu, or net. + * + * @return the limit on the resource requested. + */ + int64_t get_resource_limit(account_name account, name resource) const; + + /** + * Proposes a schedule change using the legacy producer key format. + * + * @ingroup privileged + * + * @param packed_producer_schedule - vector of producer keys + * + * @return -1 if proposing a new producer schedule was unsuccessful, otherwise returns the version of the new proposed schedule. + */ int64_t set_proposed_producers(legacy_span packed_producer_schedule); + + /** + * Proposes a schedule change with extended features. + * + * Valid formats: + * 0 : serialized array of producer_keys. Using this format is exactly equivalent to set_proposed_producers + * 1 : serialized array of producer_authority's + * + * @ingroup privileged + * + * @param packed_producer_format - format of the producer data blob + * @param packed_producer_schedule - packed data of representing the producer schedule in the format indicated. + * + * @return -1 if proposing a new producer schedule was unsuccessful, otherwise returns the version of the new proposed schedule. + */ int64_t set_proposed_producers_ex(uint64_t packed_producer_format, legacy_span packed_producer_schedule); + + /** + * Retrieve the blockchain config parameters. + * + * @ingroup privileged + * + * @param[out] packed_blockchain_parameters - output buffer of the blockchain parameters. + * + * return the number of bytes copied to the buffer, or number of bytes required if the buffer is empty. + */ uint32_t get_blockchain_parameters_packed(legacy_span packed_blockchain_parameters) const; + + /** + * Set the blockchain parameters. + * + * @ingroup privileged + * + * @param packed_parameters - a span containing the packed blockchain config parameters. + */ void set_blockchain_parameters_packed(legacy_span packed_blockchain_parameters); + + /** + * Update a single resource limit associated with an account. + * + * @ingroup privileged + * + * @param packed_parameters - a span containing the parameters to the function, for a complete reference check https://github.com/EOSIO/spec-repo/blob/master/esr_configurable_wasm_limits.md + * @param max_version - the resource to update, which should be either ram, disk, cpu, or net. + */ uint32_t get_parameters_packed( span packed_parameter_ids, span packed_parameters) const; + + /** + * Update a single resource limit associated with an account. + * + * @ingroup privileged + * + * @param packed_parameters - a span containing the parameters to the function, for a complete reference check https://github.com/EOSIO/spec-repo/blob/master/esr_configurable_wasm_limits.md + * @param max_version - the resource to update, which should be either ram, disk, cpu, or net. + */ void set_parameters_packed( span packed_parameters ); - uint32_t get_kv_parameters_packed(name, span, uint32_t) const; - void set_kv_parameters_packed(name, span); + + /** + * Gets the maximum key size, maximum value size, and maximum iterators of a kv database and returns the size of the data. + * The kv parameters are encoded as 16 bytes, representing four 32-bit little-endian values. + * +-------+---------------+---------------+---------------+---------------+ + * | byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |10 |11 |12 |13 |14 |15 | + * +-------+---------------+---------------+---------------+---------------+ + * | field | version | key limit | value limit | max iterators | + * +-------+---------------+---------------+---------------+---------------+ + * | type | 0 | 32-bits LE | 32-bits LE | 32-bits LE | + * +-------+---------------+---------------+---------------+---------------+ + * + * @ingroup privileged + * @param[out] packed_kv_parameters - the buffer containing the packed kv parameters. + * @param max_version - has no effect, but should be 0. + * + * @return Returns the size required in the buffer (if the buffer is too small, nothing is written). + * + */ + uint32_t get_kv_parameters_packed(name db, span packed_kv_parameters, uint32_t max_version) const; + + /** + * Sets the maximum key size, and maximum value size, and maximum iterators of a kv database. + * Each database has independent limits. The key and value limits only apply to new items. + * They do not apply to items written before they were applied. + * If the database is invalid, if version is non-zero, or if buffer_size is less than 16, aborts the transaction. + * + * @ingroup privileged + * @param packed_kv_parameters - the buffer containing the packed kv parameters to be set. + */ + void set_kv_parameters_packed(name db, span packed_kv_parameters); + + /** + * Check if an account is privileged + * + * @ingroup privileged + * @param account - name of the account to be checked + * + * @retval true if the account is privileged + * @retval false otherwise + */ bool is_privileged(account_name account) const; + + /** + * Set the privileged status of an account + * + * @ingroup privileged + * @param account - name of the account that we want to give the privileged status. + * @param is_priv - privileged status (true or false). + */ void set_privileged(account_name account, bool is_priv); // softfloat api @@ -100,89 +349,649 @@ namespace webassembly { double _eosio_ui32_to_f64(uint32_t) const; double _eosio_ui64_to_f64(uint64_t) const; - // producer api - int32_t get_active_producers(legacy_span) const; - - // crypto api - void assert_recover_key(legacy_ptr, legacy_span, legacy_span) const; - int32_t recover_key(legacy_ptr, legacy_span, legacy_span) const; - void assert_sha256(legacy_span, legacy_ptr) const; - void assert_sha1(legacy_span, legacy_ptr) const; - void assert_sha512(legacy_span, legacy_ptr) const; - void assert_ripemd160(legacy_span, legacy_ptr) const; - void sha256(legacy_span, legacy_ptr) const; - void sha1(legacy_span, legacy_ptr) const; - void sha512(legacy_span, legacy_ptr) const; - void ripemd160(legacy_span, legacy_ptr) const; - - // permission api - bool check_transaction_authorization(legacy_span, legacy_span, legacy_span) const; - bool check_permission_authorization(account_name, permission_name, legacy_span, legacy_span, uint64_t) const; - int64_t get_permission_last_used(account_name, permission_name) const; - int64_t get_account_creation_time(account_name) const; - - // authorization api - void require_auth(account_name) const; - void require_auth2(account_name, permission_name) const; - bool has_auth(account_name) const; - void require_recipient(account_name); - bool is_account(account_name) const; - - // system api + /** + * Get the list of active producer names. + * + * @ingroup producer + * @param[out] producers - output buffer containing the names of the current active producer names. + * + * @return number of bytes required (if the buffer is empty), or the number of bytes written to the buffer. + */ + int32_t get_active_producers(legacy_span producers) const; + + /** + * Tests a given public key with the recovered public key from digest and signature. + * + * @ingroup crypto + * @param digest - digest of the message that was signed. + * @param sig - signature. + * @param pub - public key. + */ + void assert_recover_key(legacy_ptr digest, legacy_span sig, legacy_span pub) const; + + /** + * Calculates the public key used for a given signature on a given digest. + * + * @ingroup crypto + * @param digest - digest of the message that was signed. + * @param sig - signature. + * @param[out] pub - output buffer for the public key result. + * + * @return size of data written on the buffer. + */ + int32_t recover_key(legacy_ptr digest, legacy_span sig, legacy_span pub) const; + + /** + * Tests if the sha256 hash generated from data matches the provided digest. + * + * @ingroup crypto + * @param data - a span containing the data you want to hash. + * @param hash_val - digest to compare to. + */ + void assert_sha256(legacy_span data, legacy_ptr hash_val) const; + + /** + * Tests if the sha1 hash generated from data matches the provided digest. + * + * @ingroup crypto + * @param data - a span containing the data you want to hash. + * @param hash_val - digest to compare to. + */ + void assert_sha1(legacy_span data, legacy_ptr hash_val) const; + + /** + * Tests if the sha512 hash generated from data matches the provided digest. + * + * @ingroup crypto + * @param data - a span containing the data you want to hash. + * @param hash_val - digest to compare to. + */ + void assert_sha512(legacy_span data, legacy_ptr hash_val) const; + + /** + * Tests if the ripemd160 hash generated from data matches the provided digest. + * + * @ingroup crypto + * @param data - a span containing the data you want to hash. + * @param hash_val - digest to compare to. + */ + void assert_ripemd160(legacy_span data, legacy_ptr hash_val) const; + + /** + * Hashes data using SHA256. + * + * @ingroup crypto + * @param data - a span containing the data. + * @param[out] hash_val - the resulting digest. + */ + void sha256(legacy_span data, legacy_ptr hash_val) const; + + /** + * Hashes data using SHA1. + * + * @ingroup crypto + * @param data - a span containing the data. + * @param hash_val - the resulting digest. + */ + void sha1(legacy_span data, legacy_ptr hash_val) const; + + /** + * Hashes data using SHA512. + * + * @ingroup crypto + * @param data - a span containing the data. + * @param hash_val - the hash + */ + void sha512(legacy_span data, legacy_ptr hash_val) const; + + /** + * Tests if the ripemd160 hash generated from data matches the provided digest. + * + * @ingroup crypto + * @param data - a span containing the data + * @param hash_val - the resulting digest. + */ + void ripemd160(legacy_span data, legacy_ptr hash_val) const; + + /** + * Checks if a transaction is authorized by a provided set of keys and permissions. + * + * @ingroup permission + * @param trx_data - serialized transaction. + * @param pubkeys_data - serialized vector of provided public keys. + * @param perms_data - serialized vector of provided permissions (empty permission name acts as wildcard). + * + * @retval true if transaction is authorized. + * @retval false otherwise. + */ + bool check_transaction_authorization(legacy_span trx_data, legacy_span pubkeys_data, legacy_span perms_data) const; + + /** + * Checks if a permission is authorized by a provided delay and a provided set of keys and permissions. + * + * @ingroup permission + * @param account - the account owner of the permission. + * @param permission - the name of the permission to check for authorization. + * @param pubkeys_data - serialized vector of provided public keys. + * @param perms_data - serialized vector of provided permissions (empty permission name acts as wildcard). + * @param delay_us - the provided delay in microseconds (cannot exceed INT64_MAX) + * + * @retval true if permission is authorized. + * @retval false otherwise. + */ + bool check_permission_authorization(account_name account, permission_name permission, legacy_span pubkeys_data, legacy_span perms_data, uint64_t delay_us) const; + + /** + * Returns the last used time of a permission. + * + * @ingroup permission + * @param account - the account owner of the permission. + * @param permission - the name of the permission. + * + * @return the last used time (in microseconds since Unix epoch) of the permission. + */ + int64_t get_permission_last_used(account_name account, permission_name permission) const; + + /** + * Returns the creation time of an account. + * + * @ingroup permission + * @param account - the account name. + * + * @return the creation time (in microseconds since Unix epoch) of the account. + */ + int64_t get_account_creation_time(account_name account) const; + + /** + * Verifies that Name exists in the set of provided auths on a action. Fails if not found. + * + * @ingroup authorization + * @param account - name of the account to be verified + */ + void require_auth(account_name account) const; + + /** + * Verifies that the account exists in the set of provided auths on a action + * + * @ingroup authorization + * @param account - + * @param permission - + */ + void require_auth2(account_name account, permission_name permission) const; + + /** + * Verifies that an account has auth. + * + * @ingroup authorization + * @param account - name of the account to be verified. + * + * @retval true if the account has auth. + * @retval false otherwise. + */ + bool has_auth(account_name account) const; + + /** + * Add the specified account to set of accounts to be notified. + * + * @ingroup authorization + * @param recipient - account to be notified. + */ + void require_recipient(account_name recipient); + + /** + * Verifies that n is an existing account. + * + * @ingroup authorization + * @param account - name of the account to check + * + * @return true if the account exists. + * @return false otherwise. + */ + bool is_account(account_name account) const; + + /** + * Returns the time in microseconds from 1970 of the current block. + * + * @ingroup system + * + * @return time in microseconds from 1970 of the current block + */ uint64_t current_time() const; + + /** + * Returns the transaction's publication time. + * + * @ingroup system + * + * @return time in microseconds from 1970 of the publication_time. + */ uint64_t publication_time() const; - bool is_feature_activated(legacy_ptr) const; + + /** + * Check if specified protocol feature has been activated. + * + * @ingroup system + * @param feature_digest - digest of the protocol feature. + * + * @retval true if the specified protocol feature has been activated. + * @retval false otherwise + */ + bool is_feature_activated(legacy_ptr feature_digest) const; + + /** + * Return the name of the account that sent the current inline action. + * + * @ingroup system + * @return name of account that sent the current inline action (empty name if not called from inline action). + */ name get_sender() const; - // context-free system api + /** + * Aborts processing of this action and unwinds all pending changes if the test condition is true + * + * @ingroup context-free + */ void abort() const; - void eosio_assert(bool, null_terminated_ptr) const; - void eosio_assert_message(bool, legacy_span) const; - void eosio_assert_code(bool, uint64_t) const; - void eosio_exit(int32_t) const; - // action api - int32_t read_action_data(legacy_span) const; + /** + * Aborts processing of this action if the test condition is true. + * + * @ingroup context-free + * @param condition - test condition. + * @return name of account that sent current inline action + */ + void eosio_assert(bool condition, null_terminated_ptr msg) const; + + /** + * Aborts processing of this action if the test condition is true. + * + * @ingroup context-free + * @param condition - test condition. + * @param msg - string explaining the reason for failure. + */ + void eosio_assert_message(bool condition, legacy_span msg) const; + + /** + * Aborts processing of this action if the test condition is true. + * + * @ingroup context-free + * @param condition - test condition. + * @param error_code - + */ + void eosio_assert_code(bool condition, uint64_t error_code) const; + + /** + * This method will abort execution of wasm without failing the contract + * + * @ingroup context-free + * @param code - the exit code + */ + void eosio_exit(int32_t code) const; + + /** + * Copy up to length bytes of current action data to the specified location + * + * @ingroup action + * @param memory - a pointer where up to length bytes of the current action data will be copied + * + * @return the number of bytes copied to msg, or number of bytes that can be copied if len==0 passed + */ + int32_t read_action_data(legacy_span memory) const; + + /** + * Get the length of the current action's data field. This method is useful for dynamically sized actions + * + * @ingroup action + * @return the length of the current action's data field + */ int32_t action_data_size() const; + + /** + * Get the current receiver of the action. + * + * @ingroup action + * @return the name of the receiver + */ name current_receiver() const; - void set_action_return_value(span); - - // console api - void prints(null_terminated_ptr); - void prints_l(legacy_span); - void printi(int64_t); - void printui(uint64_t); - void printi128(legacy_ptr); - void printui128(legacy_ptr); - void printsf(float32_t); - void printdf(float64_t); - void printqf(legacy_ptr); - void printn(name); - void printhex(legacy_span); + + /** + * Sets a value (packed blob char array) to be included in the action receipt. + * + * @ingroup action + * @param packed_blob - the packed blob + */ + void set_action_return_value(span packed_blob); + + /** + * Print a string. + * + * @ingroup console + * @param str - the string to print + */ + void prints(null_terminated_ptr str); + + /** + * Prints string up to given length. + * + * @ingroup console + * @param str - the string to print + */ + void prints_l(legacy_span str); + + /** + * Prints value as a 64 bit signed integer. + * + * @ingroup console + * @param val - 64 bit signed integer to be printed + */ + void printi(int64_t val); + + /** + * Prints value as a 64 bit unsigned integer. + * + * @ingroup console + * @param val - 64 bit unsigned integer to be printed + */ + void printui(uint64_t val); + + /** + * Prints value as a 128 bit signed integer. + * + * @ingroup console + * @param val - 128 bit signed integer to be printed + */ + void printi128(legacy_ptr val); + + /** + * Prints value as a 128 bit unsigned integer. + * + * @ingroup console + * @param val - 128 bit unsigned integer to be printed + */ + void printui128(legacy_ptr val); + + /** + * Prints value as single-precision floating point number (i.e. float) + * + * @ingroup console + * @param val - float to be printed + */ + void printsf(float32_t val); + + /** + * Prints value as double-precision floating point number (i.e. double) + * + * @ingroup console + * @param value - float to be printed + */ + void printdf(float64_t val); + + /** + * Prints value as quadruple-precision floating point number (i.e. long double) + * + * @ingroup console + * @param val - a pointer to the long double to be printed + */ + void printqf(legacy_ptr val); + + /** + * Prints a 64 bit names as base32 encoded string. + * + * @ingroup console + * @param value - 64 bit name to be printed + */ + void printn(name value); + + /** + * Prints a 64 bit names as base32 encoded string + * + * @ingroup console + * @param data - Hex name to be printed + */ + void printhex(legacy_span data); // database api // primary index api - int32_t db_store_i64(uint64_t, uint64_t, uint64_t, uint64_t, legacy_span); - void db_update_i64(int32_t, uint64_t, legacy_span); - void db_remove_i64(int32_t); - int32_t db_get_i64(int32_t, legacy_span); + + /** + * Store a record in a primary 64-bit integer index table + * + * @ingroup database primary-index + * @param scope - The scope where the record will be stored + * @param table - The name of the table within the current scope context + * @param payer - The account that is paying for this storage + * @param id - id of the entry + * @param buffer - record to store + * + * @return iterator to the newly created object + */ + int32_t db_store_i64(uint64_t scope, uint64_t table, uint64_t payer, uint64_t id, legacy_span buffer); + + /** + * Update a record inside a primary 64-bit integer index table. + * + * @ingroup database primary-index + * @param itr - iterator of the record to update + * @param payer - the account that is paying for this storage + * @param buffer - new updated record + */ + void db_update_i64(int32_t itr, uint64_t payer, legacy_span buffer); + + /** + * Remove a record inside a primary 64-bit integer index table. + * + * @ingroup database primary-index + * @param itr - the iterator pointing to the record to remove. + */ + void db_remove_i64(int32_t itr); + + /** + * Get a record inside a primary 64-bit integer index table. + * + * @ingroup database primary-index + * @param itr - the iterator to the record + * @param buffer - the buffer which will be filled with the retrieved record + * + * @return size of the retrieved record + */ + int32_t db_get_i64(int32_t itr, legacy_span buffer); + + /** + * Get the next record after the given iterator from a primary 64-bit integer index table. + * + * @ingroup database primary-index + * @param itr - the iterator to the record + * @param primary - it will be contain the primary key of the next record + * + * @return iterator to the next record + */ int32_t db_next_i64(int32_t, legacy_ptr); - int32_t db_previous_i64(int32_t, legacy_ptr); - int32_t db_find_i64(uint64_t, uint64_t, uint64_t, uint64_t); - int32_t db_lowerbound_i64(uint64_t, uint64_t, uint64_t, uint64_t); - int32_t db_upperbound_i64(uint64_t, uint64_t, uint64_t, uint64_t); - int32_t db_end_i64(uint64_t, uint64_t, uint64_t); - - // uint64_t secondary index api - int32_t db_idx64_store(uint64_t, uint64_t, uint64_t, uint64_t, legacy_ptr); - void db_idx64_update(int32_t, uint64_t, legacy_ptr); - void db_idx64_remove(int32_t); - int32_t db_idx64_find_secondary(uint64_t, uint64_t, uint64_t, legacy_ptr, legacy_ptr); - int32_t db_idx64_find_primary(uint64_t, uint64_t, uint64_t, legacy_ptr, uint64_t); - int32_t db_idx64_lowerbound(uint64_t, uint64_t, uint64_t, legacy_ptr, legacy_ptr); - int32_t db_idx64_upperbound(uint64_t, uint64_t, uint64_t, legacy_ptr, legacy_ptr); - int32_t db_idx64_end(uint64_t, uint64_t, uint64_t); - int32_t db_idx64_next(int32_t, legacy_ptr); + + /** + * Get the previous record before the given iterator from a primary 64-bit integer index table. + * + * @ingroup database primary-index + * @param itr - the iterator to the record + * @param primary - it will be contain the primary key of the previous record + * + * @return iterator to the previous record + */ + int32_t db_previous_i64(int32_t itr, legacy_ptr primary); + + /** + * Find a record inside a primary 64-bit integer index table. + * + * @ingroup database primary-index + * @param code - the name of the owner of the table + * @param scope - the scope where the table resides + * @param table - the table name where the record is stored + * @param id - the primary key of the record to look up + * + * @return iterator to the found record + */ + int32_t db_find_i64(uint64_t code, uint64_t scope, uint64_t table, uint64_t id); + + /** + * Find the lowerbound record given a key inside a primary 64-bit integer index table. + * Lowerbound record is the first nearest record which primary key is <= the given key. + * + * @ingroup database primary-index + * @param code - the name of the owner of the table + * @param scope - the scope where the table resides + * @param table - the table name where the record is stored + * @param id - the primary key used as a pivot to determine the lowerbound record + * + * @return iterator to the lowerbound record + */ + int32_t db_lowerbound_i64(uint64_t code, uint64_t scope, uint64_t table, uint64_t id); + + /** + * Find the upperbound record given a key inside a primary 64-bit integer index table. + * Upperbound record is the first nearest record which primary key is < the given key. + * + * @ingroup database primary-index + * @param code - the name of the owner of the table + * @param scope - the scope where the table resides + * @param table - the table name where the record is stored + * @param id - the primary key used as a pivot to determine the lowerbound record + * + * @return iterator to the upperbound record + */ + int32_t db_upperbound_i64(uint64_t code, uint64_t scope, uint64_t table, uint64_t id); + + /** + * Find the latest record inside a primary 64-bit integer index table. + * + * @ingroup database primary-index + * @param code - the name of the owner of the table + * @param scope - the scope where the table resides + * @param table - the table name where the record is stored + * + * @return iterator to the last record + */ + int32_t db_end_i64(uint64_t code, uint64_t scope, uint64_t table); + + /** + * Store a record's secondary index in a secondary 64-bit integer index table. + * + * @ingroup database uint64_t-secondary-index + * @param scope - the scope where the secondary index will be stored. + * @param table - the table name where the secondary index will be stored. + * @param payer - the account that is paying for this storage. + * @param id - the primary key of the record which secondary index to be stored. + * @param secondary - the pointer to the key of the secondary index to store. + * + * @return iterator to the newly created secondary index + */ + int32_t db_idx64_store(uint64_t scope, uint64_t table, uint64_t payer, uint64_t id, legacy_ptr secondary); + + /** + * Update a record's secondary index inside a secondary 64-bit integer index table. + * + * @ingroup database uint64_t-secondary-index + * @param iterator - the iterator to the secondary index. + * @param payer - the account that is paying for this storage. + * @param secondary - the pointer to the new key of the secondary index. + */ + void db_idx64_update(int32_t iterator, uint64_t payer, legacy_ptr secondary); + + /** + * Remove a record's secondary index from a secondary 64-bit integer index table. + * + * @ingroup database uint64_t-secondary-index + * @param iterator - The iterator to the secondary index to be removed + */ + void db_idx64_remove(int32_t iterator); + + /** + * Get the secondary index of a record from a secondary 64-bit integer index table given the secondary index key. + * + * @ingroup database uint64_t-secondary-index + * @param code - the owner of the secondary index table + * @param scope - the scope where the secondary index resides + * @param table - the table where the secondary index resides + * @param secondary - the pointer to the secondary index key + * @param primary - it will be replaced with the primary key of the record which the secondary index contains + * + * @return iterator to the secondary index which contains the given secondary index key + */ + int32_t db_idx64_find_secondary(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); + + /** + * Get the secondary index of a record from a secondary 64-bit integer index table given the record's primary key. + * + * @ingroup database uint64_t-secondary-index + * @param code - the owner of the secondary index table + * @param scope - the scope where the secondary index resides + * @param table - the table where the secondary index resides + * @param secondary - it will be replaced with the secondary index key + * @param primary - the record's primary key + * + * @return iterator to the secondary index which contains the given record's primary key + */ + int32_t db_idx64_find_primary(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, uint64_t primary); + + /** + * Get the lowerbound secondary index from a secondary 64-bit integer index table given the secondary index key. + * Lowerbound secondary index is the first secondary index which key is <= the given secondary index key + * + * @ingroup database uint64_t-secondary-index + * @param code - the owner of the secondary index table + * @param scope - the scope where the secondary index resides + * @param table - the table where the secondary index resides + * @param secondary - the pointer to the secondary index key which acts as lowerbound pivot point, later on it will be replaced with the lowerbound secondary index key + * @param primary - it will be replaced with the primary key of the record which the lowerbound secondary index contains + * + * @return iterator to the lowerbound secondary index + */ + int32_t db_idx64_lowerbound(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); + + /** + * Find the upperbound record given a key inside a primary 64-bit integer index table. + * + * @ingroup database uint64_t-secondary-index + * @param code - the owner of the secondary index table. + * @param scope - the scope where the secondary index resides. + * @param table - the table where the secondary index resides. + * @param primary - the pointer to the secondary index key which acts as upperbound pivot point, later on it will be replaced with the upperbound secondary index key. + * @param secondary - it will be replaced with the primary key of the record which the upperbound secondary index contains. + * + * @return iterator to the upperbound secondary index + */ + int32_t db_idx64_upperbound(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); + + /** + * Get the last secondary index from a secondary 64-bit integer index table. + * + * @ingroup database uint64_t-secondary-index + * @param code - the owner of the secondary index table + * @param scope - the scope where the secondary index resides + * @param table - the table where the secondary index resides + * + * @return iterator to the last secondary index + */ + int32_t db_idx64_end(uint64_t code, uint64_t scope, uint64_t table); + + /** + * Get the next secondary index inside a secondary 64-bit integer index table. + * + * @ingroup database uint64_t-secondary-index + * @param iterator - the iterator to the secondary index. + * @param primary - it will be replaced with the primary key of the record which is stored in the next secondary index. + * + * @return iterator to the next secondary index + */ + int32_t db_idx64_next(int32_t iterator, legacy_ptr primary); + + /** + * Get the previous secondary index inside a secondary 64-bit integer index table. + * + * @ingroup database uint64_t-secondary-index + * @param iterator - the iterator to the record + * @param primary - it will be replaced with the primary key of the record which is stored in the previous secondary index + * + * @return iterator to the previous secondary index + */ int32_t db_idx64_previous(int32_t, legacy_ptr); // uint128_t secondary index api @@ -233,22 +1042,194 @@ namespace webassembly { int32_t db_idx_long_double_next(int32_t, legacy_ptr); int32_t db_idx_long_double_previous(int32_t, legacy_ptr); - // kv database api - int64_t kv_erase(uint64_t, uint64_t, span); - int64_t kv_set(uint64_t, uint64_t, span, span, account_name payer); - bool kv_get(uint64_t, uint64_t, span, uint32_t*); - uint32_t kv_get_data(uint64_t, uint32_t, span); - uint32_t kv_it_create(uint64_t, uint64_t, span); - void kv_it_destroy(uint32_t); - int32_t kv_it_status(uint32_t); - int32_t kv_it_compare(uint32_t, uint32_t); - int32_t kv_it_key_compare(uint32_t, span); - int32_t kv_it_move_to_end(uint32_t); - int32_t kv_it_next(uint32_t, uint32_t* found_key_size, uint32_t* found_value_size); - int32_t kv_it_prev(uint32_t, uint32_t* found_key_size, uint32_t* found_value_size); - int32_t kv_it_lower_bound(uint32_t, span, uint32_t* found_key_size, uint32_t* found_value_size); - int32_t kv_it_key(uint32_t, uint32_t, span, uint32_t*); - int32_t kv_it_value(uint32_t, uint32_t, span dest, uint32_t*); + /** + * Erase a key-value pair. + * + * @ingroup kv-database + * @param contract - name of the contract associated with the kv pair. + * @param key - the key associated with the kv pair to be erased. + * + * @return change in resource usage. + */ + int64_t kv_erase(uint64_t db, uint64_t contract, span key); + + /** + * Set a key-value pair. + * If the key doesn't exist, then a new kv pair will be created. + * + * @ingroup kv-database + * @param contract - name of the contract associated with the kv pair. + * @param key - the key in the kv pair. + * @param value - the value in the kv pair. + * @param payer - name of the account paying for the resource. + * + * @return change in resource usage. + */ + int64_t kv_set(uint64_t db, uint64_t contract, span key, span value, account_name payer); + + /** + * Check the existence of a key. + * If the key doesn't exist, it returns false, clears the temporary data buffer and sets *value_size to 0. + * If the key does exist, it returns true, stores the value into the temporary data buffer, + * and sets *value_size to the value size. + * Use kv_get_data to retrieve the value. + * + * @ingroup kv-database + * @param contract - name of the contract associated with the kv pair. + * @param key - the key to query. + * @param[out] value_size - resulting value size (0 if the key doesn't exist). + * + * @return false if the provided key doesn't exist, true otherwise. + */ + bool kv_get(uint64_t db, uint64_t contract, span key, uint32_t* value_size); + + /** + * Fetches data from temporary buffer starting at offset. + * Copies up to the data's size span passed as parameter. + * + * @ingroup kv-database + * @param offset - position from where to start reading the value from the temporary buffer. + * @param[out] data - span where the result value will be stored. + * + * @return number of bytes written in data + */ + uint32_t kv_get_data(uint64_t, uint32_t offset, span data); + + /** + * Create a kv iterator. + * The returned handle: + * - Starts at 1. + * - Counts up by 1 at each call, assuming no destroyed iterators are available. + * - If destroyed iterators are available, the most-recently-destroyed one is reinitialized and returned. + * The prefix limits the range of keys that the iterator covers. If the prefix is empty, + * the iterator covers the entire range of keys belonging to a contract within the database ID. + * + * @ingroup kv-database + * @param contract - the contract associated with the kv iterator. + * @param prefix - prefix to build the iterator. + * + * @return handle of the created iterator + */ + uint32_t kv_it_create(uint64_t, uint64_t contract, span prefix); + + /** + * Destroy a kv iterator. + * + * @ingroup kv-database + * @param itr - the iterator to destroy. + */ + void kv_it_destroy(uint32_t itr); + + /** + * Get the status of a kv iterator. + * + * @ingroup kv-database + * @param itr - the kv iterator we want to know the status. + * + * @retval iterator_ok iterator is positioned at a kv pair. + * @retval iterator_erased the kv pair that the iterator used to be positioned at, was erased. + * @retval iterator_end iterator is out-of-bounds. + */ + int32_t kv_it_status(uint32_t itr); + + /** + * Compare the key of two kv iterators. + * + * @ingroup kv-database + * @param itr_a - first iterator. + * @param itr_b - second iterator. + * + * @retval -1 if itr_a's key is less than itr_b's key + * @retval 0 if itr_a's key is the same as itr_b's key + * @retval 1 if itr_a's key is greater than itr_b's key + */ + int32_t kv_it_compare(uint32_t itr_a, uint32_t itr_b); + + /** + * Compare the key of an iterator to a provided key. + * + * @ingroup kv-database + * @param itr - the iterator to compare. + * @param key - the key to compare. + * + * @reval -1 if itr's key is less than key. + * @retval 0 if itr's key is the same as key. + * @retval 1 itr's key is greater than key. + */ + int32_t kv_it_key_compare(uint32_t itr, span key); + + /** + * Move a kv iterator to an out-of-bounds position. + * + * @ingroup kv-database + * @param itr - the kv iterator we want to move. + * + * @return the status of the iterator (iterator_end). + */ + int32_t kv_it_move_to_end(uint32_t itr); + + /** + * Move a kv iterator to the next position. + * + * @ingroup kv-database + * @param itr - the iterator we want to move. + * @param [out] found_key_size - size of the result key in the new position. + * @param [out] found_value_size - size of the result value in the new position. + * + * @return the status of the iterator. + */ + int32_t kv_it_next(uint32_t itr, uint32_t* found_key_size, uint32_t* found_value_size); + + /** + * Move a kv iterator to the previous position. + * + * @ingroup kv-database + * @param itr - the iterator we want to move + * @param [out] found_key_size - size of the result key in the new position. + * @param [out] found_value_size - size of the result value in the new position. + * + * @return the status of the iterator. + */ + int32_t kv_it_prev(uint32_t itr, uint32_t* found_key_size, uint32_t* found_value_size); + + /** + * Find the least non-deleted key which is >= the provided key. + * + * @ingroup kv-database + * @param itr + * @param key - the key we want to query + * @param found_key_size - size of the result found key + * @param found_value_size - size of the result found value + * + * @return the status of the iterator. + */ + int32_t kv_it_lower_bound(uint32_t itr, span key, uint32_t* found_key_size, uint32_t* found_value_size); + + /** + * Fetch the key from a kv iterator. + * + * @ingroup kv-database + * @param itr - the kv iterator. + * @param offset - position from where to start reading. + * @param dest - where the data will reside. + * @param [out] actual_size - size of the key + * + * @return the status of the iterator passed as a parameter. + */ + int32_t kv_it_key(uint32_t itr, uint32_t offset, span dest, uint32_t* actual_size); + + /** + * Fetch the value from a kv iterator. + * + * @ingroup kv-database + * @param itr - the iterator of the object we want to get the value. + * @param offset - position from where to start reading. + * @param dest - where the data will reside. + * @param [out] actual_size - size of the value. + * + * @return the status of the iterator passed as a parameter. + */ + int32_t kv_it_value(uint32_t itr, uint32_t offset, span dest, uint32_t* actual_size); // memory api void* memcpy(memcpy_params) const; @@ -256,19 +1237,105 @@ namespace webassembly { int32_t memcmp(memcmp_params) const; void* memset(memset_params) const; - // transaction api - void send_inline(legacy_span); - void send_context_free_inline(legacy_span); - void send_deferred(legacy_ptr, account_name, legacy_span, uint32_t); - bool cancel_deferred(legacy_ptr); + /** + * Send an inline action in the context of the parent transaction of this operation. + * + * @ingroup transaction + * @param data - the inline action to be sent. + */ + void send_inline(legacy_span data); + + /** + * Send a context free inline action in the context of the parent transaction of this operation. + * + * @ingroup transaction + * @param data - the packed free inline action to be sent. + */ + void send_context_free_inline(legacy_span data); + + /** + * Send a deferred transaction. + * + * @ingroup transaction + * @param sender_id - account name of the sender of this deferred transaction. + * @param payer - account name responsible for paying the RAM for this deferred transaction. + * @param data - the packed transaction to be deferred + * @param replace_existing - if true, it will replace an existing transaction. + */ + void send_deferred(legacy_ptr sender_id, account_name payer, legacy_span data, uint32_t replace_existing); + + /** + * Cancels a deferred transaction. + * + * @ingroup transaction + * @param val - The id of the sender + * + * @retval false if transaction was not found + * @retval true if transaction was canceled + */ + bool cancel_deferred(legacy_ptr val); // context-free transaction api + + /** + * Access a copy of the currently executing transaction. + * + * @ingroup transaction + * @param[out] data - the currently executing transaction (packed). + * + * @retval false if transaction was not found + * @retval true if transaction was canceled + */ int32_t read_transaction(legacy_span) const; + + /** + * Gets the size of the currently executing transaction. + * + * @ingroup transaction + * + * @return size of the currently executing transaction + */ int32_t transaction_size() const; + + /** + * Gets the expiration of the currently executing transaction. + * + * @ingroup transaction + * + * @return expiration of the currently executing transaction in seconds since Unix epoch + */ int32_t expiration() const; + + /** + * Gets the block number used for TAPOS on the currently executing transaction. + * + * @ingroup transaction + * + * @return block number used for TAPOS on the currently executing transaction. + */ int32_t tapos_block_num() const; + + /** + * Gets the block prefix used for TAPOS on the currently executing transaction. + * + * @ingroup transaction + * + * @return block prefix used for TAPOS on the currently executing transaction. + */ int32_t tapos_block_prefix() const; - int32_t get_action(uint32_t, uint32_t, legacy_span) const; + + /** + * Retrieve the indicated action from the active transaction. + * + * @ingroup transaction + * + * @param type - 0 for context free action, 1 for action. + * @param index - the index of the requested action. + * @param[out] buffer - the action we want (packed). + * + * @return the number of bytes written on the buffer or -1 if there was an error. + */ + int32_t get_action(uint32_t type, uint32_t index, legacy_span buffer) const; // compiler builtins api void __ashlti3(legacy_ptr, uint64_t, uint64_t, uint32_t) const; diff --git a/libraries/chain/webassembly/privileged.cpp b/libraries/chain/webassembly/privileged.cpp index 95419484cff..e80f8e965f9 100644 --- a/libraries/chain/webassembly/privileged.cpp +++ b/libraries/chain/webassembly/privileged.cpp @@ -42,15 +42,6 @@ namespace eosio { namespace chain { namespace webassembly { (void)legacy_ptr(std::move(cpu_weight)); } - /** - * update a single resource limit associated with an account. - * - * @param account - the account whose limits are being modified - * @param resource - the resource to update, which should be either ram, disk, cpu, or net. - * @param limit - the new limit. A value of -1 means unlimited. - * - * @pre limit >= -1 - */ void interface::set_resource_limit( account_name account, name resource, int64_t limit ) { EOS_ASSERT(limit >= -1, wasm_execution_error, "invalid value for ${resource} resource limit expected [-1,INT64_MAX]", ("resource", resource)); auto& manager = context.control.get_mutable_resource_limits_manager(); From 8cce66b13e9860c5dbdff274c4ae05e0d31ee720 Mon Sep 17 00:00:00 2001 From: Victor Camacho Date: Thu, 17 Sep 2020 08:42:51 -0400 Subject: [PATCH 02/14] document some host functions --- .../eosio/chain/webassembly/interface.hpp | 239 ++++++++++-------- 1 file changed, 133 insertions(+), 106 deletions(-) diff --git a/libraries/chain/include/eosio/chain/webassembly/interface.hpp b/libraries/chain/include/eosio/chain/webassembly/interface.hpp index 7471b8b0f61..cd4649eb66a 100644 --- a/libraries/chain/include/eosio/chain/webassembly/interface.hpp +++ b/libraries/chain/include/eosio/chain/webassembly/interface.hpp @@ -750,30 +750,32 @@ namespace webassembly { */ void printhex(legacy_span data); - // database api - // primary index api - /** - * Store a record in a primary 64-bit integer index table + * Store a record in a primary 64-bit integer index table. * * @ingroup database primary-index - * @param scope - The scope where the record will be stored - * @param table - The name of the table within the current scope context - * @param payer - The account that is paying for this storage - * @param id - id of the entry - * @param buffer - record to store * - * @return iterator to the newly created object - */ + * @param scope - the scope where the table resides (implied to be within the code of the current receiver). + * @param table - the name of the table within the current scope context. + * @param payer - the account that pays for the storage. + * @param id - id of the entry. + * @param buffer - record to store. + * + * @return iterator to the newly created table row. + * @post a new entry is created in the table. + */ int32_t db_store_i64(uint64_t scope, uint64_t table, uint64_t payer, uint64_t id, legacy_span buffer); /** - * Update a record inside a primary 64-bit integer index table. + * Update a record in a primary 64-bit integer index table. * * @ingroup database primary-index - * @param itr - iterator of the record to update - * @param payer - the account that is paying for this storage - * @param buffer - new updated record + * @param itr - iterator to the table row containing the record to update. + * @param payer - the account that pays for the storage costs. + * @param buffer - new updated record. + * + * @pre `itr` points to an existing table row in the table. + * @post the record contained in the table row pointed to by `itr` is replaced with the new updated record. */ void db_update_i64(int32_t itr, uint64_t payer, legacy_span buffer); @@ -781,216 +783,241 @@ namespace webassembly { * Remove a record inside a primary 64-bit integer index table. * * @ingroup database primary-index - * @param itr - the iterator pointing to the record to remove. + * @param itr - the terator to the table row to remove. + * + * @pre `itr` points to an existing table row in the tab. */ void db_remove_i64(int32_t itr); /** - * Get a record inside a primary 64-bit integer index table. + * Get a record in a primary 64-bit integer index table. * * @ingroup database primary-index - * @param itr - the iterator to the record - * @param buffer - the buffer which will be filled with the retrieved record + * @param itr - the iterator to the table row containing the record to retrieve. + * @param[out] buffer - the buffer which will be filled with the retrieved record. * - * @return size of the retrieved record + * @return size of the data copied into the buffer if buffer is not empty, or size of the retrieved record if the buffer is empty. + * @pre `itr` points to an existing table row in the table. + * @post `buffer` will be filled with the retrieved record (truncated to the first `len` bytes if necessary). */ int32_t db_get_i64(int32_t itr, legacy_span buffer); /** - * Get the next record after the given iterator from a primary 64-bit integer index table. + * Find the table row following the referenced table row in a primary 64-bit integer index table. * * @ingroup database primary-index - * @param itr - the iterator to the record - * @param primary - it will be contain the primary key of the next record + * @param itr - the iterator to the referenced table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the next table row. + * + * @return iterator to the table row following the referenced table row (or the end iterator of the table if the referenced table row is the last one in the table). * - * @return iterator to the next record + * @post '*primary' will be replaced with the primary key of the table row following the referenced table row if it exists, otherwise primary will be left untouched. */ - int32_t db_next_i64(int32_t, legacy_ptr); + int32_t db_next_i64(int32_t itr, legacy_ptr primary); /** - * Get the previous record before the given iterator from a primary 64-bit integer index table. + * Find the table row preceding the referenced table row in a primary 64-bit integer index table. * * @ingroup database primary-index - * @param itr - the iterator to the record - * @param primary - it will be contain the primary key of the previous record + * @param itr - the iterator to the referenced table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the next table row. * - * @return iterator to the previous record + * @return iterator to the table row preceding the referenced table row assuming one exists (it will return -1 if the referenced table row is the first one in the table). + * @post '*primary' will be replaced with the primary key of the table row preceding the referenced table row if it exists, otherwise primary will be left untouched. */ int32_t db_previous_i64(int32_t itr, legacy_ptr primary); /** - * Find a record inside a primary 64-bit integer index table. + * Find a table row in a primary 64-bit integer index table by primary key. * * @ingroup database primary-index - * @param code - the name of the owner of the table - * @param scope - the scope where the table resides - * @param table - the table name where the record is stored - * @param id - the primary key of the record to look up + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param id - the primary key of the record to look up. * - * @return iterator to the found record + * @return iterator to the table row with a primary key equal to id or the end iterator of the table if the table row could not be found. */ int32_t db_find_i64(uint64_t code, uint64_t scope, uint64_t table, uint64_t id); /** - * Find the lowerbound record given a key inside a primary 64-bit integer index table. + * Find the table row in a primary 64-bit integer index table that matches the lowerbound condition for a given primary key. * Lowerbound record is the first nearest record which primary key is <= the given key. * * @ingroup database primary-index - * @param code - the name of the owner of the table - * @param scope - the scope where the table resides - * @param table - the table name where the record is stored - * @param id - the primary key used as a pivot to determine the lowerbound record + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param id - the primary key used as a pivot to determine the lowerbound record. * - * @return iterator to the lowerbound record + * @return iterator to the lowerbound record or the end iterator of the table if the table row could not be found. */ int32_t db_lowerbound_i64(uint64_t code, uint64_t scope, uint64_t table, uint64_t id); /** - * Find the upperbound record given a key inside a primary 64-bit integer index table. - * Upperbound record is the first nearest record which primary key is < the given key. + * Find the table row in a primary 64-bit integer index table that matches the upperbound condition for a given primary key. + * The table row that matches the upperbound condition is the first table row in the table with the lowest primary key that is > the given key. * * @ingroup database primary-index - * @param code - the name of the owner of the table - * @param scope - the scope where the table resides - * @param table - the table name where the record is stored - * @param id - the primary key used as a pivot to determine the lowerbound record + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param id - the primary key used as a pivot to determine the upperbound record. * - * @return iterator to the upperbound record + * @return iterator to the upperbound record or the end iterator of the table if the table row could not be found. */ int32_t db_upperbound_i64(uint64_t code, uint64_t scope, uint64_t table, uint64_t id); /** - * Find the latest record inside a primary 64-bit integer index table. + * Get an iterator representing just-past-the-end of the last table row of a primary 64-bit integer index table. * * @ingroup database primary-index - * @param code - the name of the owner of the table - * @param scope - the scope where the table resides - * @param table - the table name where the record is stored + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. * - * @return iterator to the last record + * @return end iterator of the table. */ int32_t db_end_i64(uint64_t code, uint64_t scope, uint64_t table); /** - * Store a record's secondary index in a secondary 64-bit integer index table. + * Store an association of a 64-bit integer secondary key to a primary key in a secondary 64-bit integer index table. * * @ingroup database uint64_t-secondary-index - * @param scope - the scope where the secondary index will be stored. - * @param table - the table name where the secondary index will be stored. + * @param scope - the scope where the table resides (implied to be within the code of the current receiver). + * @param table - the table name. * @param payer - the account that is paying for this storage. - * @param id - the primary key of the record which secondary index to be stored. + * @param id - the primary key to which to associate the secondary key. * @param secondary - the pointer to the key of the secondary index to store. * - * @return iterator to the newly created secondary index + * @return iterator to the newly created secondary index. + * @post new secondary key association between primary key `id` and secondary key `*secondary` is created in the secondary 64-bit integer index table. */ int32_t db_idx64_store(uint64_t scope, uint64_t table, uint64_t payer, uint64_t id, legacy_ptr secondary); /** - * Update a record's secondary index inside a secondary 64-bit integer index table. + * Update an association for a 64-bit integer secondary key to a primary key in a secondary 64-bit integer index table. * * @ingroup database uint64_t-secondary-index - * @param iterator - the iterator to the secondary index. - * @param payer - the account that is paying for this storage. - * @param secondary - the pointer to the new key of the secondary index. + * @param iterator - the iterator to the table row containing the secondary key association to update. + * @param payer - the account that pays for the storage costs. + * @param secondary - pointer to the **new** secondary key that will replace the existing one of the association. + * + * @pre `iterator` points to an existing table row in the table. + * @post the secondary key of the table row pointed to by `iterator` is replaced by `*secondary`. */ void db_idx64_update(int32_t iterator, uint64_t payer, legacy_ptr secondary); /** - * Remove a record's secondary index from a secondary 64-bit integer index table. + * Remove a table row from a secondary 64-bit integer index table. * * @ingroup database uint64_t-secondary-index - * @param iterator - The iterator to the secondary index to be removed + * @param iterator - iterator to the table row to remove. + * + * @pre `iterator` points to an existing table row in the table. + * @post the table row pointed to by `iterator` is removed and the associated storage costs are refunded to the payer. */ void db_idx64_remove(int32_t iterator); /** - * Get the secondary index of a record from a secondary 64-bit integer index table given the secondary index key. + * Find a table row in a secondary 64-bit integer index table by secondary key. * * @ingroup database uint64_t-secondary-index - * @param code - the owner of the secondary index table - * @param scope - the scope where the secondary index resides - * @param table - the table where the secondary index resides - * @param secondary - the pointer to the secondary index key - * @param primary - it will be replaced with the primary key of the record which the secondary index contains * - * @return iterator to the secondary index which contains the given secondary index key + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param secondary - the pointer to the secondary index key. + * @param[out] primary - pointer to a 'uint64_t' variable which will have its value set to the primary key of the found table row. + * + * @return iterator to the first table row with a secondary key equal to `*secondary` or the end iterator of the table if the table row could not be found. + * @post If and only if the table row is found, `*primary` will be replaced with the primary key of the found table row. */ int32_t db_idx64_find_secondary(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); /** - * Get the secondary index of a record from a secondary 64-bit integer index table given the record's primary key. + * Find a table row in a secondary 64-bit integer index table by primary key. * * @ingroup database uint64_t-secondary-index - * @param code - the owner of the secondary index table - * @param scope - the scope where the secondary index resides - * @param table - the table where the secondary index resides - * @param secondary - it will be replaced with the secondary index key - * @param primary - the record's primary key - * - * @return iterator to the secondary index which contains the given record's primary key + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param[out] secondary - pointer to a 'uint64_t' variable which will have its value set to the secondary key of the found table row. + * @param primary - the primary key of the table row to look up. + * + * @return iterator to the table row with a primary key equal to `primary` or the end iterator of the table if the table row could not be found. + * @post If and only if the table row is found, `*secondary` will be replaced with the secondary key of the found table row. */ int32_t db_idx64_find_primary(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, uint64_t primary); /** - * Get the lowerbound secondary index from a secondary 64-bit integer index table given the secondary index key. + * Find the table row in a secondary 64-bit integer index table that matches the lowerbound condition for a given secondary key. * Lowerbound secondary index is the first secondary index which key is <= the given secondary index key * * @ingroup database uint64_t-secondary-index - * @param code - the owner of the secondary index table - * @param scope - the scope where the secondary index resides - * @param table - the table where the secondary index resides - * @param secondary - the pointer to the secondary index key which acts as lowerbound pivot point, later on it will be replaced with the lowerbound secondary index key - * @param primary - it will be replaced with the primary key of the record which the lowerbound secondary index contains + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param[out] secondary - pointer to secondary key first used to determine the lowerbound and which is then replaced with the secondary key of the found table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. + * + * @return iterator to the found table row or the end iterator of the table if the table row could not be found. * - * @return iterator to the lowerbound secondary index + * @post If and only if the table row is found, `*secondary` will be replaced with the secondary key of the found table row. + * @post If and only if the table row is found, `*primary` will be replaced with the primary key of the found table row. */ int32_t db_idx64_lowerbound(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); /** - * Find the upperbound record given a key inside a primary 64-bit integer index table. + * Find the table row in a secondary 64-bit integer index table that matches the upperbound condition for a given secondary key. + * The table row that matches the upperbound condition is the first table row in the table with the lowest secondary key that is > the given key * * @ingroup database uint64_t-secondary-index - * @param code - the owner of the secondary index table. - * @param scope - the scope where the secondary index resides. - * @param table - the table where the secondary index resides. - * @param primary - the pointer to the secondary index key which acts as upperbound pivot point, later on it will be replaced with the upperbound secondary index key. - * @param secondary - it will be replaced with the primary key of the record which the upperbound secondary index contains. + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param seconday - pointer to secondary key first used to determine the upperbound and which is then replaced with the secondary key of the found table row. + * @param primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. * - * @return iterator to the upperbound secondary index + * @return iterator to the found table row or the end iterator of the table if the table row could not be found. */ int32_t db_idx64_upperbound(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); /** - * Get the last secondary index from a secondary 64-bit integer index table. + * Get an end iterator representing just-past-the-end of the last table row of a secondary 64-bit integer index table. * * @ingroup database uint64_t-secondary-index - * @param code - the owner of the secondary index table - * @param scope - the scope where the secondary index resides - * @param table - the table where the secondary index resides + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. * - * @return iterator to the last secondary index + * @return end iterator of the table. */ int32_t db_idx64_end(uint64_t code, uint64_t scope, uint64_t table); /** - * Get the next secondary index inside a secondary 64-bit integer index table. + * Find the table row following the referenced table row in a secondary 64-bit integer index table. * * @ingroup database uint64_t-secondary-index - * @param iterator - the iterator to the secondary index. - * @param primary - it will be replaced with the primary key of the record which is stored in the next secondary index. + * @param iterator - the iterator to the referenced table row. + * @param primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the next table row. * - * @return iterator to the next secondary index + * @return iterator to the table row following the referenced table row (or the end iterator of the table if the referenced table row is the last one in the table). + * @pre `iterator` points to an existing table row in the table. + * @post `*primary` will be replaced with the primary key of the table row following the referenced table row if it exists, otherwise `*primary` will be left untouched. */ int32_t db_idx64_next(int32_t iterator, legacy_ptr primary); /** - * Get the previous secondary index inside a secondary 64-bit integer index table. + * Find the table row preceding the referenced table row in a secondary 64-bit integer index table. * * @ingroup database uint64_t-secondary-index - * @param iterator - the iterator to the record - * @param primary - it will be replaced with the primary key of the record which is stored in the previous secondary index + * @param iterator - the iterator to the referenced table row. + * @param primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the previous table row. * - * @return iterator to the previous secondary index + * @return iterator to the table row preceding the referenced table row assuming one exists (it will return -1 if the referenced table row is the first one in the table). + * @pre `iterator` points to an existing table row in the table or it is the end iterator of the table. + * @post `*primary` will be replaced with the primary key of the table row preceding the referenced table row if it exists, otherwise `*primary` will be left untouched. */ int32_t db_idx64_previous(int32_t, legacy_ptr); From d8f7d19cadf2bed5e305526dc052427208a303b2 Mon Sep 17 00:00:00 2001 From: Victor Camacho Date: Thu, 17 Sep 2020 09:16:25 -0400 Subject: [PATCH 03/14] document some host functions --- .../include/eosio/chain/webassembly/interface.hpp | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/libraries/chain/include/eosio/chain/webassembly/interface.hpp b/libraries/chain/include/eosio/chain/webassembly/interface.hpp index cd4649eb66a..85bb4dac246 100644 --- a/libraries/chain/include/eosio/chain/webassembly/interface.hpp +++ b/libraries/chain/include/eosio/chain/webassembly/interface.hpp @@ -952,7 +952,7 @@ namespace webassembly { /** * Find the table row in a secondary 64-bit integer index table that matches the lowerbound condition for a given secondary key. - * Lowerbound secondary index is the first secondary index which key is <= the given secondary index key + * Lowerbound secondary index is the first secondary index which key is <= the given secondary index key. * * @ingroup database uint64_t-secondary-index * @param code - the name of the owner of the table. @@ -970,13 +970,13 @@ namespace webassembly { /** * Find the table row in a secondary 64-bit integer index table that matches the upperbound condition for a given secondary key. - * The table row that matches the upperbound condition is the first table row in the table with the lowest secondary key that is > the given key + * The table row that matches the upperbound condition is the first table row in the table with the lowest secondary key that is > the given key. * * @ingroup database uint64_t-secondary-index * @param code - the name of the owner of the table. * @param scope - the scope where the table resides. * @param table - the table name. - * @param seconday - pointer to secondary key first used to determine the upperbound and which is then replaced with the secondary key of the found table row. + * @param secondary - pointer to secondary key first used to determine the upperbound and which is then replaced with the secondary key of the found table row. * @param primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. * * @return iterator to the found table row or the end iterator of the table if the table row could not be found. @@ -1000,7 +1000,7 @@ namespace webassembly { * * @ingroup database uint64_t-secondary-index * @param iterator - the iterator to the referenced table row. - * @param primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the next table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the next table row. * * @return iterator to the table row following the referenced table row (or the end iterator of the table if the referenced table row is the last one in the table). * @pre `iterator` points to an existing table row in the table. @@ -1013,7 +1013,7 @@ namespace webassembly { * * @ingroup database uint64_t-secondary-index * @param iterator - the iterator to the referenced table row. - * @param primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the previous table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the previous table row. * * @return iterator to the table row preceding the referenced table row assuming one exists (it will return -1 if the referenced table row is the first one in the table). * @pre `iterator` points to an existing table row in the table or it is the end iterator of the table. From cc4ecd87d1e13019b0ebe312e34ee4610ab72e47 Mon Sep 17 00:00:00 2001 From: Victor Camacho Date: Thu, 17 Sep 2020 09:34:47 -0400 Subject: [PATCH 04/14] document some host functions --- .../eosio/chain/webassembly/interface.hpp | 151 ++++++++++++++++-- 1 file changed, 140 insertions(+), 11 deletions(-) diff --git a/libraries/chain/include/eosio/chain/webassembly/interface.hpp b/libraries/chain/include/eosio/chain/webassembly/interface.hpp index 85bb4dac246..54f081ed240 100644 --- a/libraries/chain/include/eosio/chain/webassembly/interface.hpp +++ b/libraries/chain/include/eosio/chain/webassembly/interface.hpp @@ -1021,17 +1021,146 @@ namespace webassembly { */ int32_t db_idx64_previous(int32_t, legacy_ptr); - // uint128_t secondary index api - int32_t db_idx128_store(uint64_t, uint64_t, uint64_t, uint64_t, legacy_ptr); - void db_idx128_update(int32_t, uint64_t, legacy_ptr); - void db_idx128_remove(int32_t); - int32_t db_idx128_find_secondary(uint64_t, uint64_t, uint64_t, legacy_ptr, legacy_ptr); - int32_t db_idx128_find_primary(uint64_t, uint64_t, uint64_t, legacy_ptr, uint64_t); - int32_t db_idx128_lowerbound(uint64_t, uint64_t, uint64_t, legacy_ptr, legacy_ptr); - int32_t db_idx128_upperbound(uint64_t, uint64_t, uint64_t, legacy_ptr, legacy_ptr); - int32_t db_idx128_end(uint64_t, uint64_t, uint64_t); - int32_t db_idx128_next(int32_t, legacy_ptr); - int32_t db_idx128_previous(int32_t, legacy_ptr); + /** + * Store an association of a 128-bit integer secondary key to a primary key in a secondary 128-bit integer index table. + * + * @ingroup database uint128_t-secondary-index + * @param scope - the scope where the table resides (implied to be within the code of the current receiver). + * @param table - the table name. + * @param payer - the account that is paying for this storage. + * @param id - the primary key to which to associate the secondary key. + * @param secondary - the pointer to the key of the secondary index to store. + * + * @return iterator to the newly created secondary index. + * @post new secondary key association between primary key `id` and secondary key `*secondary` is created in the secondary 128-bit integer index table. + */ + int32_t db_idx128_store(uint64_t scope, uint64_t table, uint64_t payer, uint64_t id, legacy_ptr secondary); + + /** + * Update an association for a 128-bit integer secondary key to a primary key in a secondary 128-bit integer index table. + * + * @ingroup database uint128_t-secondary-index + * @param iterator - the iterator to the table row containing the secondary key association to update. + * @param payer - the account that pays for the storage costs. + * @param secondary - pointer to the **new** secondary key that will replace the existing one of the association. + * + * @pre `iterator` points to an existing table row in the table. + * @post the secondary key of the table row pointed to by `iterator` is replaced by `*secondary`. + */ + void db_idx128_update(int32_t iterator, uint64_t payer, legacy_ptr secondary); + + /** + * Remove a table row from a secondary 128-bit integer index table. + * + * @ingroup database uint128_t-secondary-index + * @param iterator - iterator to the table row to remove. + * + * @pre `iterator` points to an existing table row in the table. + * @post the table row pointed to by `iterator` is removed and the associated storage costs are refunded to the payer. + */ + void db_idx128_remove(int32_t iterator); + + /** + * Find a table row in a secondary 128-bit integer index table by secondary key. + * + * @ingroup database uint128_t-secondary-index + * + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param secondary - the pointer to the secondary index key. + * @param[out] primary - pointer to a 'uint128_t' variable which will have its value set to the primary key of the found table row. + * + * @return iterator to the first table row with a secondary key equal to `*secondary` or the end iterator of the table if the table row could not be found. + * @post If and only if the table row is found, `*primary` will be replaced with the primary key of the found table row. + */ + int32_t db_idx128_find_secondary(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); + + /** + * Find a table row in a secondary 128-bit integer index table by primary key. + * + * @ingroup database uint128_t-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param[out] secondary - pointer to a 'uint128_t' variable which will have its value set to the secondary key of the found table row. + * @param primary - the primary key of the table row to look up. + * + * @return iterator to the table row with a primary key equal to `primary` or the end iterator of the table if the table row could not be found. + * @post If and only if the table row is found, `*secondary` will be replaced with the secondary key of the found table row. + */ + int32_t db_idx128_find_primary(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, uint64_t primary); + + /** + * Find the table row in a secondary 128-bit integer index table that matches the lowerbound condition for a given secondary key. + * Lowerbound secondary index is the first secondary index which key is <= the given secondary index key. + * + * @ingroup database uint128_t-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param[out] secondary - pointer to secondary key first used to determine the lowerbound and which is then replaced with the secondary key of the found table row. + * @param[out] primary - pointer to a `uint128_t` variable which will have its value set to the primary key of the found table row. + * + * @return iterator to the found table row or the end iterator of the table if the table row could not be found. + * + * @post If and only if the table row is found, `*secondary` will be replaced with the secondary key of the found table row. + * @post If and only if the table row is found, `*primary` will be replaced with the primary key of the found table row. + */ + int32_t db_idx128_lowerbound(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); + + /** + * Find the table row in a secondary 128-bit integer index table that matches the upperbound condition for a given secondary key. + * The table row that matches the upperbound condition is the first table row in the table with the lowest secondary key that is > the given key. + * + * @ingroup database uint128_t-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param secondary - pointer to secondary key first used to determine the upperbound and which is then replaced with the secondary key of the found table row. + * @param primary - pointer to a `uint128_t` variable which will have its value set to the primary key of the found table row. + * + * @return iterator to the found table row or the end iterator of the table if the table row could not be found. + */ + int32_t db_idx128_upperbound(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); + + /** + * Get an end iterator representing just-past-the-end of the last table row of a secondary 128-bit integer index table. + * + * @ingroup database uint128_t-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * + * @return end iterator of the table. + */ + int32_t db_idx128_end(uint64_t code, uint64_t scope, uint64_t table); + + /** + * Find the table row following the referenced table row in a secondary 128-bit integer index table. + * + * @ingroup database uint128_t-secondary-index + * @param iterator - the iterator to the referenced table row. + * @param[out] primary - pointer to a `uint128_t` variable which will have its value set to the primary key of the next table row. + * + * @return iterator to the table row following the referenced table row (or the end iterator of the table if the referenced table row is the last one in the table). + * @pre `iterator` points to an existing table row in the table. + * @post `*primary` will be replaced with the primary key of the table row following the referenced table row if it exists, otherwise `*primary` will be left untouched. + */ + int32_t db_idx128_next(int32_t iterator, legacy_ptr primary); + + /** + * Find the table row preceding the referenced table row in a secondary 128-bit integer index table. + * + * @ingroup database uint128_t-secondary-index + * @param iterator - the iterator to the referenced table row. + * @param[out] primary - pointer to a `uint128_t` variable which will have its value set to the primary key of the previous table row. + * + * @return iterator to the table row preceding the referenced table row assuming one exists (it will return -1 if the referenced table row is the first one in the table). + * @pre `iterator` points to an existing table row in the table or it is the end iterator of the table. + * @post `*primary` will be replaced with the primary key of the table row preceding the referenced table row if it exists, otherwise `*primary` will be left untouched. + */ + int32_t db_idx128_previous(int32_t iterator, legacy_ptr primary); // 256-bit secondary index api int32_t db_idx256_store(uint64_t, uint64_t, uint64_t, uint64_t, legacy_span); From c4754a39f2d95afb0b9a7e80ecd74892c0745399 Mon Sep 17 00:00:00 2001 From: Victor Camacho Date: Thu, 17 Sep 2020 17:31:19 -0400 Subject: [PATCH 05/14] document some host functions --- .../eosio/chain/webassembly/interface.hpp | 234 ++++++++++++++---- 1 file changed, 191 insertions(+), 43 deletions(-) diff --git a/libraries/chain/include/eosio/chain/webassembly/interface.hpp b/libraries/chain/include/eosio/chain/webassembly/interface.hpp index 54f081ed240..ca99357033a 100644 --- a/libraries/chain/include/eosio/chain/webassembly/interface.hpp +++ b/libraries/chain/include/eosio/chain/webassembly/interface.hpp @@ -23,7 +23,7 @@ namespace webassembly { * @param index - the index of the context_free_data entry to retrieve. * @param[out] buffer - output buffer of the context_free_data entry. * - * @retval -1 if the index is not valid + * @retval -1 if the index is not valid. * @retval size of the cfd if the buffer is empty, otherwise return the amount of data copied onto the buffer. */ int32_t get_context_free_data(uint32_t index, legacy_span buffer) const; @@ -64,7 +64,7 @@ namespace webassembly { * @ingroup privileged * * @param account - name of the account whose resource limit to be set. - * @param ram_bytes -ram limit in absolute bytes. + * @param ram_bytes - ram limit in absolute bytes. * @param net_weight - fractionally proportionate net limit of available resources based on (weight / total_weight_of_all_accounts). * @param cpu_weight - fractionally proportionate cpu limit of available resources based on (weight / total_weight_of_all_accounts). */ @@ -76,7 +76,7 @@ namespace webassembly { * @ingroup privileged * * @param account - name of the account whose resource limit to get. - * @param[out] ram_bytes - output to hold retrieved ram limit in absolute bytes. + * @param[out] ram_bytes - output to hold retrieved ram limit in absolute bytes. * @param[out] net_weight - output to hold net weight. * @param[out] cpu_weight - output to hold cpu weight. */ @@ -219,22 +219,38 @@ namespace webassembly { void set_blockchain_parameters_packed(legacy_span packed_blockchain_parameters); /** - * Update a single resource limit associated with an account. - * + * Retrieve the blockchain config parameters. + * The input buffer is a packed data stream which represents an encoded sequence of parameter_id pairs with the following format: + * |varuint32:sequence_length | varuint32:parameter_id | ... + * The output buffer is a packed data stream which represents an encoded sequence of parameter_id:paramter_value pairs with the following format: + * |varuint32:sequence_length | varuint32:parameter_id | :parameter_value | ... + * The encoding of parameter_values should be specific to the parameter being set + * The output buffer format should be valid input for set_parameters_packed. + * For each known parameter_id in the input sequence there should be an associated entry in the output sequence with the current encoded parameter_value. + * + * @brief Retrieve the blockchain config parameters. * @ingroup privileged * - * @param packed_parameters - a span containing the parameters to the function, for a complete reference check https://github.com/EOSIO/spec-repo/blob/master/esr_configurable_wasm_limits.md - * @param max_version - the resource to update, which should be either ram, disk, cpu, or net. + * @param packed_parameter_ids - the input buffer with the format as described above. + * @param[out] packed_parameters - the output buffer with the format as described above. */ uint32_t get_parameters_packed( span packed_parameter_ids, span packed_parameters) const; /** - * Update a single resource limit associated with an account. - * + * Set the blockchain parameters. + * It allows a system contract the ability to set parameters in a flexible manner. + * The input buffer is a packed data stream which represents an encoded sequence of parameter_id:paramter_value pairs with the following format: + * |varuint32:sequence_length | varuint32:parameter_id | :parameter_value | ... + * The encoding of parameter_values should be specific to the parameter being set. + * Having duplicate parameter_ids encoded in the sequence should result in aborting the transaction context. + * The presence of a parameter_id which is unknown OR which is known but tied to an unactivated consensus protocol + * should result in aborting the transaction context. + * There are no requirement for the ordering of items in the sequence. + * + * @brief Set the blockchain parameters in a flexible manner. * @ingroup privileged * - * @param packed_parameters - a span containing the parameters to the function, for a complete reference check https://github.com/EOSIO/spec-repo/blob/master/esr_configurable_wasm_limits.md - * @param max_version - the resource to update, which should be either ram, disk, cpu, or net. + * @param packed_parameters - buffer to hold the packed data with the format described above. */ void set_parameters_packed( span packed_parameters ); @@ -431,7 +447,7 @@ namespace webassembly { * * @ingroup crypto * @param data - a span containing the data. - * @param hash_val - the resulting digest. + * @param[out] hash_val - the resulting digest. */ void sha1(legacy_span data, legacy_ptr hash_val) const; @@ -440,16 +456,16 @@ namespace webassembly { * * @ingroup crypto * @param data - a span containing the data. - * @param hash_val - the hash + * @param[out] hash_val - the hash */ void sha512(legacy_span data, legacy_ptr hash_val) const; /** - * Tests if the ripemd160 hash generated from data matches the provided digest. + * Hashes data using RIPEMD160. * * @ingroup crypto - * @param data - a span containing the data - * @param hash_val - the resulting digest. + * @param data - a span containing the data. + * @param[out] hash_val - computed digest. */ void ripemd160(legacy_span data, legacy_ptr hash_val) const; @@ -503,29 +519,29 @@ namespace webassembly { int64_t get_account_creation_time(account_name account) const; /** - * Verifies that Name exists in the set of provided auths on a action. Fails if not found. + * Verifies that an account exists in the set of provided auths on an action. Fails if not found. * * @ingroup authorization - * @param account - name of the account to be verified + * @param account - the name of the account to be verified. */ void require_auth(account_name account) const; /** - * Verifies that the account exists in the set of provided auths on a action + * Verifies that an account with a specific permission exists in the set of provided auths on an action, * * @ingroup authorization - * @param account - - * @param permission - + * @param account - the name of the account to be verified. + * @param permission - the name of the permission to be verified. */ void require_auth2(account_name account, permission_name permission) const; /** - * Verifies that an account has auth. + * Test whether an account exists in the set of provided auths on an action. * * @ingroup authorization - * @param account - name of the account to be verified. + * @param account - name of the account to be tested. * - * @retval true if the account has auth. + * @retval true if the action has an auth with the account name. * @retval false otherwise. */ bool has_auth(account_name account) const; @@ -976,8 +992,8 @@ namespace webassembly { * @param code - the name of the owner of the table. * @param scope - the scope where the table resides. * @param table - the table name. - * @param secondary - pointer to secondary key first used to determine the upperbound and which is then replaced with the secondary key of the found table row. - * @param primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. + * @param[out] secondary - pointer to secondary key first used to determine the upperbound and which is then replaced with the secondary key of the found table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. * * @return iterator to the found table row or the end iterator of the table if the table row could not be found. */ @@ -1069,7 +1085,7 @@ namespace webassembly { * @param scope - the scope where the table resides. * @param table - the table name. * @param secondary - the pointer to the secondary index key. - * @param[out] primary - pointer to a 'uint128_t' variable which will have its value set to the primary key of the found table row. + * @param[out] primary - pointer to a 'uint64_t' variable which will have its value set to the primary key of the found table row. * * @return iterator to the first table row with a secondary key equal to `*secondary` or the end iterator of the table if the table row could not be found. * @post If and only if the table row is found, `*primary` will be replaced with the primary key of the found table row. @@ -1100,7 +1116,7 @@ namespace webassembly { * @param scope - the scope where the table resides. * @param table - the table name. * @param[out] secondary - pointer to secondary key first used to determine the lowerbound and which is then replaced with the secondary key of the found table row. - * @param[out] primary - pointer to a `uint128_t` variable which will have its value set to the primary key of the found table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. * * @return iterator to the found table row or the end iterator of the table if the table row could not be found. * @@ -1117,8 +1133,8 @@ namespace webassembly { * @param code - the name of the owner of the table. * @param scope - the scope where the table resides. * @param table - the table name. - * @param secondary - pointer to secondary key first used to determine the upperbound and which is then replaced with the secondary key of the found table row. - * @param primary - pointer to a `uint128_t` variable which will have its value set to the primary key of the found table row. + * @param secondary[out] - pointer to secondary key first used to determine the upperbound and which is then replaced with the secondary key of the found table row. + * @param primary[out] - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. * * @return iterator to the found table row or the end iterator of the table if the table row could not be found. */ @@ -1141,7 +1157,7 @@ namespace webassembly { * * @ingroup database uint128_t-secondary-index * @param iterator - the iterator to the referenced table row. - * @param[out] primary - pointer to a `uint128_t` variable which will have its value set to the primary key of the next table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the next table row. * * @return iterator to the table row following the referenced table row (or the end iterator of the table if the referenced table row is the last one in the table). * @pre `iterator` points to an existing table row in the table. @@ -1154,7 +1170,7 @@ namespace webassembly { * * @ingroup database uint128_t-secondary-index * @param iterator - the iterator to the referenced table row. - * @param[out] primary - pointer to a `uint128_t` variable which will have its value set to the primary key of the previous table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the previous table row. * * @return iterator to the table row preceding the referenced table row assuming one exists (it will return -1 if the referenced table row is the first one in the table). * @pre `iterator` points to an existing table row in the table or it is the end iterator of the table. @@ -1162,17 +1178,149 @@ namespace webassembly { */ int32_t db_idx128_previous(int32_t iterator, legacy_ptr primary); - // 256-bit secondary index api - int32_t db_idx256_store(uint64_t, uint64_t, uint64_t, uint64_t, legacy_span); - void db_idx256_update(int32_t, uint64_t, legacy_span); - void db_idx256_remove(int32_t); - int32_t db_idx256_find_secondary(uint64_t, uint64_t, uint64_t, legacy_span, legacy_ptr); - int32_t db_idx256_find_primary(uint64_t, uint64_t, uint64_t, legacy_span, uint64_t); - int32_t db_idx256_lowerbound(uint64_t, uint64_t, uint64_t, legacy_span, legacy_ptr); - int32_t db_idx256_upperbound(uint64_t, uint64_t, uint64_t, legacy_span, legacy_ptr); - int32_t db_idx256_end(uint64_t, uint64_t, uint64_t); - int32_t db_idx256_next(int32_t, legacy_ptr); - int32_t db_idx256_previous(int32_t, legacy_ptr); + /** + * Store an association of a 256-bit integer secondary key to a primary key in a secondary 256-bit integer index table. + * + * @ingroup database 256-bit-secondary-index + * @param scope - the scope where the table resides (implied to be within the code of the current receiver). + * @param table - the table name. + * @param payer - the account that is paying for this storage. + * @param id - the primary key to which to associate the secondary key. + * @param data - pointer to the secondary key data stored as an array of 2 `uint128_t` integers. + * + * @return iterator to the newly created secondary index. + * @post new secondary key association between primary key `id` and secondary key `*secondary` is created in the secondary 256-bit integer index table. + */ + int32_t db_idx256_store(uint64_t scope, uint64_t table, uint64_t payer, uint64_t id, legacy_span data); + + /** + * Update an association for a 256-bit integer secondary key to a primary key in a secondary 256-bit integer index table. + * + * @ingroup database 256-bit-secondary-index + * @param iterator - the iterator to the table row containing the secondary key association to update. + * @param payer - the account that pays for the storage costs. + * @param data - pointer to the **new** secondary key data (which is stored as an array of 2 `uint128_t` integers) that will replace the existing one of the association. + * + * @pre `iterator` points to an existing table row in the table. + * @post the secondary key of the table row pointed to by `iterator` is replaced by the specified secondary key. + */ + void db_idx256_update(int32_t iterator, uint64_t payer, legacy_span data); + + /** + * Remove a table row from a secondary 256-bit integer index table. + * + * @ingroup database 256-bit-secondary-index + * @param iterator - iterator to the table row to remove. + * + * @pre `iterator` points to an existing table row in the table. + * @post the table row pointed to by `iterator` is removed and the associated storage costs are refunded to the payer. + */ + void db_idx256_remove(int32_t iterator); + + /** + * Find a table row in a secondary 256-bit integer index table by secondary key. + * + * @ingroup database 256-bit-secondary-index + * + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param data - pointer to the secondary key data (which is stored as an array of 2 `uint128_t` integers) used to lookup the table row. + * @param[out] primary - pointer to a 'uint64_t' variable which will have its value set to the primary key of the found table row. + * + * @return iterator to the first table row with a secondary key equal to the specified secondary key or the end iterator of the table if the table row could not be found. + * @post If and only if the table row is found, `*primary` will be replaced with the primary key of the found table row. + */ + int32_t db_idx256_find_secondary(uint64_t code, uint64_t scope, uint64_t table, legacy_span data, legacy_ptr primary); + + /** + * Find a table row in a secondary 256-bit integer index table by primary key. + * + * @ingroup database 256-bit-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param[out] data - pointer to the array of 2 `uint128_t` integers which will act as the buffer to hold the retrieved secondary key of the found table row. + * @param primary - the primary key of the table row to look up. + * + * @return iterator to the table row with a primary key equal to `data` or the end iterator of the table if the table row could not be found. + * @post If and only if the table row is found, `data` will be replaced with the secondary key of the found table row. + */ + int32_t db_idx256_find_primary(uint64_t code, uint64_t scope, uint64_t table, legacy_span data, uint64_t primary); + + /** + * Find the table row in a secondary 256-bit integer index table that matches the lowerbound condition for a given secondary key. + * Lowerbound secondary index is the first secondary index which key is <= the given secondary index key. + * + * @ingroup database 256-bit-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param[out] data - pointer to the secondary key data (which is stored as an array of 2 `uint128_t` integers) first used to determine the lowerbound and which is then replaced with the secondary key of the found table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. + * + * @return iterator to the found table row or the end iterator of the table if the table row could not be found. + * + * @post If and only if the table row is found, `data` will be replaced with the secondary key of the found table row. + * @post If and only if the table row is found, `*primary` will be replaced with the primary key of the found table row. + */ + int32_t db_idx256_lowerbound(uint64_t code, uint64_t scope, uint64_t table, legacy_span data, legacy_ptr primary); + + /** + * Find the table row in a secondary 256-bit integer index table that matches the upperbound condition for a given secondary key. + * The table row that matches the upperbound condition is the first table row in the table with the lowest secondary key that is > the given key. + * + * @ingroup database 256-bit-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param[out] data - pointer to the secondary key data (which is stored as an array of 2 `uint128_t` integers) first used to determine the upperbound and which is then replaced with the secondary key of the found table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. + * + * @return iterator to the found table row or the end iterator of the table if the table row could not be found. + * + * @post If and only if the table row is found, the buffer pointed to by `data` will be filled with the secondary key of the found table row. + * @post If and only if the table row is found, `*primary` will be replaced with the primary key of the found table row. + */ + int32_t db_idx256_upperbound(uint64_t code, uint64_t scope, uint64_t table, legacy_span data, legacy_ptr primary); + + /** + * Get an end iterator representing just-past-the-end of the last table row of a secondary 256-bit integer index table. + * + * @ingroup database 256-bit-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * + * @return end iterator of the table. + */ + int32_t db_idx256_end(uint64_t code, uint64_t scope, uint64_t table); + + /** + * Find the table row following the referenced table row in a secondary 256-bit integer index table. + * + * @ingroup database 256-bit-secondary-index + * @param iterator - the iterator to the referenced table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the next table row. + * + * @return iterator to the table row following the referenced table row (or the end iterator of the table if the referenced table row is the last one in the table). + * @pre `iterator` points to an existing table row in the table. + * @post `*primary` will be replaced with the primary key of the table row following the referenced table row if it exists, otherwise `*primary` will be left untouched. + */ + int32_t db_idx256_next(int32_t iterator, legacy_ptr primary); + + /** + * Find the table row preceding the referenced table row in a secondary 256-bit integer index table. + * + * @ingroup database 256-bit-secondary-index + * @param iterator - the iterator to the referenced table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the previous table row. + * + * @return iterator to the table row preceding the referenced table row assuming one exists (it will return -1 if the referenced table row is the first one in the table). + * @pre `iterator` points to an existing table row in the table or it is the end iterator of the table. + * @post `*primary` will be replaced with the primary key of the table row preceding the referenced table row if it exists, otherwise `*primary` will be left untouched. + */ + int32_t db_idx256_previous(int32_t iterator, legacy_ptr primary); // double secondary index api int32_t db_idx_double_store(uint64_t, uint64_t, uint64_t, uint64_t, legacy_ptr); From 1f759d988e9ce40aaeda7b3d9c8a1cbdfa8cdd36 Mon Sep 17 00:00:00 2001 From: Victor Camacho Date: Thu, 17 Sep 2020 18:33:35 -0400 Subject: [PATCH 06/14] document some host functions --- .../eosio/chain/webassembly/interface.hpp | 156 ++++++++++++++++-- 1 file changed, 144 insertions(+), 12 deletions(-) diff --git a/libraries/chain/include/eosio/chain/webassembly/interface.hpp b/libraries/chain/include/eosio/chain/webassembly/interface.hpp index ca99357033a..751f430c7a1 100644 --- a/libraries/chain/include/eosio/chain/webassembly/interface.hpp +++ b/libraries/chain/include/eosio/chain/webassembly/interface.hpp @@ -1189,7 +1189,7 @@ namespace webassembly { * @param data - pointer to the secondary key data stored as an array of 2 `uint128_t` integers. * * @return iterator to the newly created secondary index. - * @post new secondary key association between primary key `id` and secondary key `*secondary` is created in the secondary 256-bit integer index table. + * @post new secondary key association between primary key `id` and secondary key `*data` is created in the secondary 256-bit integer index table. */ int32_t db_idx256_store(uint64_t scope, uint64_t table, uint64_t payer, uint64_t id, legacy_span data); @@ -1322,17 +1322,149 @@ namespace webassembly { */ int32_t db_idx256_previous(int32_t iterator, legacy_ptr primary); - // double secondary index api - int32_t db_idx_double_store(uint64_t, uint64_t, uint64_t, uint64_t, legacy_ptr); - void db_idx_double_update(int32_t, uint64_t, legacy_ptr); - void db_idx_double_remove(int32_t); - int32_t db_idx_double_find_secondary(uint64_t, uint64_t, uint64_t, legacy_ptr, legacy_ptr); - int32_t db_idx_double_find_primary(uint64_t, uint64_t, uint64_t, legacy_ptr, uint64_t); - int32_t db_idx_double_lowerbound(uint64_t, uint64_t, uint64_t, legacy_ptr, legacy_ptr); - int32_t db_idx_double_upperbound(uint64_t, uint64_t, uint64_t, legacy_ptr, legacy_ptr); - int32_t db_idx_double_end(uint64_t, uint64_t, uint64_t); - int32_t db_idx_double_next(int32_t, legacy_ptr); - int32_t db_idx_double_previous(int32_t, legacy_ptr); + /** + * Store an association of a double-precision floating-point secondary key to a primary key in a secondary double-precision floating-point integer index table. + * + * @ingroup database double-secondary-index + * @param scope - the scope where the table resides (implied to be within the code of the current receiver). + * @param table - the table name. + * @param payer - the account that is paying for this storage. + * @param id - the primary key to which to associate the secondary key. + * @param secondary - pointer to the secondary key. + * + * @return iterator to the newly created secondary index. + * @post new secondary key association between primary key `id` and secondary key `*secondary` is created in the secondary 256-bit integer index table. + */ + int32_t db_idx_double_store(uint64_t scope, uint64_t table, uint64_t payer, uint64_t id, legacy_ptr secondary); + + /** + * Update an association for a double-precision floating-point secondary key to a primary key in a secondary double-precision floating-point integer index table. + * + * @ingroup database double-secondary-index + * @param iterator - the iterator to the table row containing the secondary key association to update. + * @param payer - the account that pays for the storage costs. + * @param secondary - pointer to the **new** secondary key that will replace the existing one of the association. + * + * @pre `iterator` points to an existing table row in the table. + * @post the secondary key of the table row pointed to by `iterator` is replaced by the specified secondary key. + */ + void db_idx_double_update(int32_t iterator, uint64_t payer, legacy_ptr secondary); + + /** + * Remove a table row from a secondary double-precision floating-point index table. + * + * @ingroup database double-secondary-index + * @param iterator - iterator to the table row to remove. + * + * @pre `iterator` points to an existing table row in the table. + * @post the table row pointed to by `iterator` is removed and the associated storage costs are refunded to the payer. + */ + void db_idx_double_remove(int32_t iterator); + + /** + * Find a table row in a secondary double-precision floating-point index table by secondary key. + * + * @ingroup database double-secondary-index + * + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param secondary - Pointer to secondary key used to lookup the table row. + * @param[out] primary - pointer to a 'uint64_t' variable which will have its value set to the primary key of the found table row. + * + * @return iterator to the first table row with a secondary key equal to the specified secondary key or the end iterator of the table if the table row could not be found. + * @post If and only if the table row is found, `*primary` will be replaced with the primary key of the found table row. + */ + int32_t db_idx_double_find_secondary(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); + + /** + * Find a table row in a secondary double-precision floating-point index table by primary key. + * + * @ingroup database double-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param[out] secondary - pointer to a `double` variable which will have its value set to the secondary key of the found table row. + * @param primary - the primary key of the table row to look up. + * + * @return iterator to the table row with a primary key equal to `secondary` or the end iterator of the table if the table row could not be found. + * @post If and only if the table row is found, `data` will be replaced with the secondary key of the found table row. + */ + int32_t db_idx_double_find_primary(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, uint64_t primary); + + /** + * Find the table row in a secondary double-precision floating-point index table that matches the lowerbound condition for a given secondary key. + * Lowerbound secondary index is the first secondary index which key is <= the given secondary index key. + * + * @ingroup database double-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param[out] secondary - Pointer to secondary key first used to determine the lowerbound and which is then replaced with the secondary key of the found table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. + * + * @return iterator to the found table row or the end iterator of the table if the table row could not be found. + * + * @post If and only if the table row is found, `*secondary` will be replaced with the secondary key of the found table row. + * @post If and only if the table row is found, `*primary` will be replaced with the primary key of the found table row. + */ + int32_t db_idx_double_lowerbound(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); + + /** + * Find the table row in a secondary double-precision floating-point index table that matches the upperbound condition for a given secondary key. + * The table row that matches the upperbound condition is the first table row in the table with the lowest secondary key that is > the given key. + * + * @ingroup database double-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param[out] secondary - pointer to secondary key first used to determine the upperbound and which is then replaced with the secondary key of the found table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. + * + * @return iterator to the found table row or the end iterator of the table if the table row could not be found. + * + * @post If and only if the table row is found, the buffer pointed to by `*secondary` will be filled with the secondary key of the found table row. + * @post If and only if the table row is found, `*primary` will be replaced with the primary key of the found table row. + */ + int32_t db_idx_double_upperbound(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); + + /** + * Get an end iterator representing just-past-the-end of the last table row of a secondary double-precision floating-point index table. + * + * @ingroup database double-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * + * @return end iterator of the table. + */ + int32_t db_idx_double_end(uint64_t code, uint64_t scope, uint64_t table); + + /** + * Find the table row following the referenced table row in a secondary double-precision floating-point index table. + * + * @ingroup database double-secondary-index + * @param iterator - the iterator to the referenced table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the next table row. + * + * @return iterator to the table row following the referenced table row (or the end iterator of the table if the referenced table row is the last one in the table). + * @pre `iterator` points to an existing table row in the table. + * @post `*primary` will be replaced with the primary key of the table row following the referenced table row if it exists, otherwise `*primary` will be left untouched. + */ + int32_t db_idx_double_next(int32_t iterator, legacy_ptr primary); + + /** + * Find the table row preceding the referenced table row in a secondary double-precision floating-point index table. + * + * @ingroup database double-secondary-index + * @param iterator - the iterator to the referenced table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the previous table row. + * + * @return iterator to the table row preceding the referenced table row assuming one exists (it will return -1 if the referenced table row is the first one in the table). + * @pre `iterator` points to an existing table row in the table or it is the end iterator of the table. + * @post `*primary` will be replaced with the primary key of the table row preceding the referenced table row if it exists, otherwise `*primary` will be left untouched. + */ + int32_t db_idx_double_previous(int32_t iterator, legacy_ptr primary); // long double secondary index api int32_t db_idx_long_double_store(uint64_t, uint64_t, uint64_t, uint64_t, legacy_ptr); From 41ef4728b14b4bebe0d00c3a6a06319a6e4aeffa Mon Sep 17 00:00:00 2001 From: Victor Camacho Date: Thu, 17 Sep 2020 19:20:39 -0400 Subject: [PATCH 07/14] document some host functions --- .../eosio/chain/webassembly/interface.hpp | 162 ++++++++++++++++-- 1 file changed, 147 insertions(+), 15 deletions(-) diff --git a/libraries/chain/include/eosio/chain/webassembly/interface.hpp b/libraries/chain/include/eosio/chain/webassembly/interface.hpp index 751f430c7a1..4dbe259e732 100644 --- a/libraries/chain/include/eosio/chain/webassembly/interface.hpp +++ b/libraries/chain/include/eosio/chain/webassembly/interface.hpp @@ -1323,7 +1323,7 @@ namespace webassembly { int32_t db_idx256_previous(int32_t iterator, legacy_ptr primary); /** - * Store an association of a double-precision floating-point secondary key to a primary key in a secondary double-precision floating-point integer index table. + * Store an association of a double-precision floating-point secondary key to a primary key in a secondary double-precision floating-point index table. * * @ingroup database double-secondary-index * @param scope - the scope where the table resides (implied to be within the code of the current receiver). @@ -1333,12 +1333,12 @@ namespace webassembly { * @param secondary - pointer to the secondary key. * * @return iterator to the newly created secondary index. - * @post new secondary key association between primary key `id` and secondary key `*secondary` is created in the secondary 256-bit integer index table. + * @post new secondary key association between primary key `id` and secondary key `*secondary` is created in the secondary double-precision floating-point index table. */ int32_t db_idx_double_store(uint64_t scope, uint64_t table, uint64_t payer, uint64_t id, legacy_ptr secondary); /** - * Update an association for a double-precision floating-point secondary key to a primary key in a secondary double-precision floating-point integer index table. + * Update an association for a double-precision floating-point secondary key to a primary key in a secondary double-precision floating-point index table. * * @ingroup database double-secondary-index * @param iterator - the iterator to the table row containing the secondary key association to update. @@ -1388,7 +1388,7 @@ namespace webassembly { * @param primary - the primary key of the table row to look up. * * @return iterator to the table row with a primary key equal to `secondary` or the end iterator of the table if the table row could not be found. - * @post If and only if the table row is found, `data` will be replaced with the secondary key of the found table row. + * @post If and only if the table row is found, `secondary` will be replaced with the secondary key of the found table row. */ int32_t db_idx_double_find_primary(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, uint64_t primary); @@ -1466,17 +1466,149 @@ namespace webassembly { */ int32_t db_idx_double_previous(int32_t iterator, legacy_ptr primary); - // long double secondary index api - int32_t db_idx_long_double_store(uint64_t, uint64_t, uint64_t, uint64_t, legacy_ptr); - void db_idx_long_double_update(int32_t, uint64_t, legacy_ptr); - void db_idx_long_double_remove(int32_t); - int32_t db_idx_long_double_find_secondary(uint64_t, uint64_t, uint64_t, legacy_ptr, legacy_ptr); - int32_t db_idx_long_double_find_primary(uint64_t, uint64_t, uint64_t, legacy_ptr, uint64_t); - int32_t db_idx_long_double_lowerbound(uint64_t, uint64_t, uint64_t, legacy_ptr, legacy_ptr); - int32_t db_idx_long_double_upperbound(uint64_t, uint64_t, uint64_t, legacy_ptr, legacy_ptr); - int32_t db_idx_long_double_end(uint64_t, uint64_t, uint64_t); - int32_t db_idx_long_double_next(int32_t, legacy_ptr); - int32_t db_idx_long_double_previous(int32_t, legacy_ptr); + /** + * Store an association of a quadruple-precision floating-point secondary key to a primary key in a secondary quadruple-precision floating-point index table. + * + * @ingroup database long-double-secondary-index + * @param scope - the scope where the table resides (implied to be within the code of the current receiver). + * @param table - the table name. + * @param payer - the account that is paying for this storage. + * @param id - the primary key to which to associate the secondary key. + * @param secondary - pointer to the secondary key. + * + * @return iterator to the newly created secondary index. + * @post new secondary key association between primary key `id` and secondary key `*secondary` is created in the quadruple-precision floating-point index table. + */ + int32_t db_idx_long_double_store(uint64_t scope, uint64_t table, uint64_t payer, uint64_t id, legacy_ptr secondary); + + /** + * Update an association for a quadruple-precision floating-point secondary key to a primary key in a secondary quadruple-precision floating-point index table. + * + * @ingroup database long-double-secondary-index + * @param iterator - the iterator to the table row containing the secondary key association to update. + * @param payer - the account that pays for the storage costs. + * @param secondary - pointer to the **new** secondary key that will replace the existing one of the association. + * + * @pre `iterator` points to an existing table row in the table. + * @post the secondary key of the table row pointed to by `iterator` is replaced by the specified secondary key. + */ + void db_idx_long_double_update(int32_t iterator, uint64_t payer, legacy_ptr secondary); + + /** + * Remove a table row from a secondary quadruple-precision floating-point index table. + * + * @ingroup database long-double-secondary-index + * @param iterator - iterator to the table row to remove. + * + * @pre `iterator` points to an existing table row in the table. + * @post the table row pointed to by `iterator` is removed and the associated storage costs are refunded to the payer. + */ + void db_idx_long_double_remove(int32_t iterator); + + /** + * Find a table row in a secondary quadruple-precision floating-point index table by secondary key. + * + * @ingroup database long-double-secondary-index + * + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param secondary - Pointer to secondary key used to lookup the table row. + * @param[out] primary - pointer to a 'uint64_t' variable which will have its value set to the primary key of the found table row. + * + * @return iterator to the first table row with a secondary key equal to the specified secondary key or the end iterator of the table if the table row could not be found. + * @post If and only if the table row is found, `*primary` will be replaced with the primary key of the found table row. + */ + int32_t db_idx_long_double_find_secondary(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); + + /** + * Find a table row in a quadruple double-precision floating-point index table by primary key. + * + * @ingroup database long-double-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param[out] secondary - pointer to a `long double` variable which will have its value set to the secondary key of the found table row. + * @param primary - the primary key of the table row to look up. + * + * @return iterator to the table row with a primary key equal to `secondary` or the end iterator of the table if the table row could not be found. + * @post If and only if the table row is found, `secondary` will be replaced with the secondary key of the found table row. + */ + int32_t db_idx_long_double_find_primary(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, uint64_t primary); + + /** + * Find the table row in a secondary quadruple-precision floating-point index table that matches the lowerbound condition for a given secondary key. + * Lowerbound secondary index is the first secondary index which key is <= the given secondary index key. + * + * @ingroup database long-double-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param[out] secondary - Pointer to secondary key first used to determine the lowerbound and which is then replaced with the secondary key of the found table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. + * + * @return iterator to the found table row or the end iterator of the table if the table row could not be found. + * + * @post If and only if the table row is found, `*secondary` will be replaced with the secondary key of the found table row. + * @post If and only if the table row is found, `*primary` will be replaced with the primary key of the found table row. + */ + int32_t db_idx_long_double_lowerbound(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); + + /** + * Find the table row in a secondary quadruple-precision floating-point index table that matches the upperbound condition for a given secondary key. + * The table row that matches the upperbound condition is the first table row in the table with the lowest secondary key that is > the given key. + * + * @ingroup database long-double-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * @param[out] secondary - pointer to secondary key first used to determine the upperbound and which is then replaced with the secondary key of the found table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. + * + * @return iterator to the found table row or the end iterator of the table if the table row could not be found. + * + * @post If and only if the table row is found, the buffer pointed to by `*secondary` will be filled with the secondary key of the found table row. + * @post If and only if the table row is found, `*primary` will be replaced with the primary key of the found table row. + */ + int32_t db_idx_long_double_upperbound(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); + + /** + * Get an end iterator representing just-past-the-end of the last table row of a secondary quadruple-precision floating-point index table. + * + * @ingroup database long-double-secondary-index + * @param code - the name of the owner of the table. + * @param scope - the scope where the table resides. + * @param table - the table name. + * + * @return end iterator of the table. + */ + int32_t db_idx_long_double_end(uint64_t code, uint64_t scope, uint64_t table); + + /** + * Find the table row following the referenced table row in a secondary quadruple-precision floating-point index table. + * + * @ingroup database long-double-secondary-index + * @param iterator - the iterator to the referenced table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the next table row. + * + * @return iterator to the table row following the referenced table row (or the end iterator of the table if the referenced table row is the last one in the table). + * @pre `iterator` points to an existing table row in the table. + * @post `*primary` will be replaced with the primary key of the table row following the referenced table row if it exists, otherwise `*primary` will be left untouched. + */ + int32_t db_idx_long_double_next(int32_t iterator, legacy_ptr primary); + + /** + * Find the table row preceding the referenced table row in a secondary quadruple-precision floating-point index table. + * + * @ingroup database long-double-secondary-index + * @param iterator - the iterator to the referenced table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the previous table row. + * + * @return iterator to the table row preceding the referenced table row assuming one exists (it will return -1 if the referenced table row is the first one in the table). + * @pre `iterator` points to an existing table row in the table or it is the end iterator of the table. + * @post `*primary` will be replaced with the primary key of the table row preceding the referenced table row if it exists, otherwise `*primary` will be left untouched. + */ + int32_t db_idx_long_double_previous(int32_t iterator, legacy_ptr primary); /** * Erase a key-value pair. From dd5b554099f050411f93b089d3a186ebf24beb49 Mon Sep 17 00:00:00 2001 From: Victor Camacho Date: Thu, 17 Sep 2020 20:45:27 -0400 Subject: [PATCH 08/14] document some host functions --- docs.json | 8 ++++++ .../eosio/chain/webassembly/interface.hpp | 27 +++++++++---------- 2 files changed, 21 insertions(+), 14 deletions(-) diff --git a/docs.json b/docs.json index 698c666cecb..16195c6fc37 100644 --- a/docs.json +++ b/docs.json @@ -60,6 +60,14 @@ "disable_filters": true, "disable_summary_gen": true } + }, + { + "name": "doxygen_to_xml", + "options": { + "INPUT": "libraries/chain/include/eosio/chain/webassembly/interface.hpp" + }, + "disable_default_filters" :true, + "filters" : [] } ] } diff --git a/libraries/chain/include/eosio/chain/webassembly/interface.hpp b/libraries/chain/include/eosio/chain/webassembly/interface.hpp index 4dbe259e732..20b8fdb13ba 100644 --- a/libraries/chain/include/eosio/chain/webassembly/interface.hpp +++ b/libraries/chain/include/eosio/chain/webassembly/interface.hpp @@ -54,7 +54,7 @@ namespace webassembly { * Allows a privileged smart contract, e.g. the system contract, to pre-activate a consensus protocol upgrade feature. * * @ingroup privileged - * @param digest_type - 256-bit digest representing the feature to pre-activate. + * @param feature_digest - 256-bit digest representing the feature to pre-activate. */ void preactivate_feature(legacy_ptr feature_digest); @@ -130,8 +130,7 @@ namespace webassembly { * @param[out] packed_parameters the ouput for the parameters. * @param max_version has no effect, but should be 0. * - * @retval the size of the packed parameters if packed_parameters is empty. - * @retval the amount of data written in packed_parameters. + * @return the size of the packed parameters if packed_parameters is empty, otherwise it returns the amount of data written in packed_parameters. */ uint32_t get_wasm_parameters_packed( span packed_parameters, uint32_t max_version ) const; @@ -186,12 +185,12 @@ namespace webassembly { * Proposes a schedule change with extended features. * * Valid formats: - * 0 : serialized array of producer_keys. Using this format is exactly equivalent to set_proposed_producers - * 1 : serialized array of producer_authority's + * 0 : serialized array of producer_keys. Using this format is exactly equivalent to set_proposed_producers. + * 1 : serialized array of producer_authority's. * * @ingroup privileged * - * @param packed_producer_format - format of the producer data blob + * @param packed_producer_format - format of the producer data blob. * @param packed_producer_schedule - packed data of representing the producer schedule in the format indicated. * * @return -1 if proposing a new producer schedule was unsuccessful, otherwise returns the version of the new proposed schedule. @@ -214,7 +213,7 @@ namespace webassembly { * * @ingroup privileged * - * @param packed_parameters - a span containing the packed blockchain config parameters. + * @param packed_blockchain_parameters - a span containing the packed blockchain config parameters. */ void set_blockchain_parameters_packed(legacy_span packed_blockchain_parameters); @@ -614,7 +613,7 @@ namespace webassembly { * * @ingroup context-free * @param condition - test condition. - * @return name of account that sent current inline action + * @param msg - string explaining the reason for failure. */ void eosio_assert(bool condition, null_terminated_ptr msg) const; @@ -738,7 +737,7 @@ namespace webassembly { * Prints value as double-precision floating point number (i.e. double) * * @ingroup console - * @param value - float to be printed + * @param val - float to be printed */ void printdf(float64_t val); @@ -1035,7 +1034,7 @@ namespace webassembly { * @pre `iterator` points to an existing table row in the table or it is the end iterator of the table. * @post `*primary` will be replaced with the primary key of the table row preceding the referenced table row if it exists, otherwise `*primary` will be left untouched. */ - int32_t db_idx64_previous(int32_t, legacy_ptr); + int32_t db_idx64_previous(int32_t iterator, legacy_ptr primary); /** * Store an association of a 128-bit integer secondary key to a primary key in a secondary 128-bit integer index table. @@ -1133,8 +1132,8 @@ namespace webassembly { * @param code - the name of the owner of the table. * @param scope - the scope where the table resides. * @param table - the table name. - * @param secondary[out] - pointer to secondary key first used to determine the upperbound and which is then replaced with the secondary key of the found table row. - * @param primary[out] - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. + * @param[out] secondary - pointer to secondary key first used to determine the upperbound and which is then replaced with the secondary key of the found table row. + * @param[out] primary - pointer to a `uint64_t` variable which will have its value set to the primary key of the found table row. * * @return iterator to the found table row or the end iterator of the table if the table row could not be found. */ @@ -1720,7 +1719,7 @@ namespace webassembly { * @param itr - the iterator to compare. * @param key - the key to compare. * - * @reval -1 if itr's key is less than key. + * @retval -1 if itr's key is less than key. * @retval 0 if itr's key is the same as key. * @retval 1 itr's key is greater than key. */ @@ -1854,7 +1853,7 @@ namespace webassembly { * @retval false if transaction was not found * @retval true if transaction was canceled */ - int32_t read_transaction(legacy_span) const; + int32_t read_transaction(legacy_span data) const; /** * Gets the size of the currently executing transaction. From 518764fdb8b66c70958409d6a5e3e145b15229cb Mon Sep 17 00:00:00 2001 From: Victor Camacho Date: Fri, 18 Sep 2020 08:28:55 -0400 Subject: [PATCH 09/14] document some host functions --- .../eosio/chain/webassembly/interface.hpp | 112 +++++++++--------- 1 file changed, 57 insertions(+), 55 deletions(-) diff --git a/libraries/chain/include/eosio/chain/webassembly/interface.hpp b/libraries/chain/include/eosio/chain/webassembly/interface.hpp index 20b8fdb13ba..2637af84d9d 100644 --- a/libraries/chain/include/eosio/chain/webassembly/interface.hpp +++ b/libraries/chain/include/eosio/chain/webassembly/interface.hpp @@ -285,10 +285,10 @@ namespace webassembly { void set_kv_parameters_packed(name db, span packed_kv_parameters); /** - * Check if an account is privileged + * Check if an account is privileged. * * @ingroup privileged - * @param account - name of the account to be checked + * @param account - name of the account to be checked. * * @retval true if the account is privileged * @retval false otherwise @@ -296,7 +296,7 @@ namespace webassembly { bool is_privileged(account_name account) const; /** - * Set the privileged status of an account + * Set the privileged status of an account. * * @ingroup privileged * @param account - name of the account that we want to give the privileged status. @@ -557,7 +557,7 @@ namespace webassembly { * Verifies that n is an existing account. * * @ingroup authorization - * @param account - name of the account to check + * @param account - name of the account to check. * * @return true if the account exists. * @return false otherwise. @@ -569,7 +569,7 @@ namespace webassembly { * * @ingroup system * - * @return time in microseconds from 1970 of the current block + * @return time in microseconds from 1970 of the current block. */ uint64_t current_time() const; @@ -589,7 +589,7 @@ namespace webassembly { * @param feature_digest - digest of the protocol feature. * * @retval true if the specified protocol feature has been activated. - * @retval false otherwise + * @retval false otherwise. */ bool is_feature_activated(legacy_ptr feature_digest) const; @@ -602,7 +602,7 @@ namespace webassembly { name get_sender() const; /** - * Aborts processing of this action and unwinds all pending changes if the test condition is true + * Aborts processing of this action and unwinds all pending changes if the test condition is true. * * @ingroup context-free */ @@ -628,10 +628,12 @@ namespace webassembly { /** * Aborts processing of this action if the test condition is true. + * It can be used to provide an error code rather than a message string on assertion checks. + * If the assertion fails, the provided error code will be made available through the exception message. * * @ingroup context-free * @param condition - test condition. - * @param error_code - + * @param error_code - the error code associated. */ void eosio_assert_code(bool condition, uint64_t error_code) const; @@ -647,9 +649,9 @@ namespace webassembly { * Copy up to length bytes of current action data to the specified location * * @ingroup action - * @param memory - a pointer where up to length bytes of the current action data will be copied + * @param memory - a pointer where up to length bytes of the current action data will be copied. * - * @return the number of bytes copied to msg, or number of bytes that can be copied if len==0 passed + * @return the number of bytes copied to msg, or number of bytes that can be copied if an empty span is passed. */ int32_t read_action_data(legacy_span memory) const; @@ -689,7 +691,7 @@ namespace webassembly { * Prints string up to given length. * * @ingroup console - * @param str - the string to print + * @param str - the string to print. */ void prints_l(legacy_span str); @@ -697,7 +699,7 @@ namespace webassembly { * Prints value as a 64 bit signed integer. * * @ingroup console - * @param val - 64 bit signed integer to be printed + * @param val - 64 bit signed integer to be printed. */ void printi(int64_t val); @@ -705,7 +707,7 @@ namespace webassembly { * Prints value as a 64 bit unsigned integer. * * @ingroup console - * @param val - 64 bit unsigned integer to be printed + * @param val - 64 bit unsigned integer to be printed. */ void printui(uint64_t val); @@ -713,7 +715,7 @@ namespace webassembly { * Prints value as a 128 bit signed integer. * * @ingroup console - * @param val - 128 bit signed integer to be printed + * @param val - 128 bit signed integer to be printed. */ void printi128(legacy_ptr val); @@ -721,31 +723,31 @@ namespace webassembly { * Prints value as a 128 bit unsigned integer. * * @ingroup console - * @param val - 128 bit unsigned integer to be printed + * @param val - 128 bit unsigned integer to be printed. */ void printui128(legacy_ptr val); /** - * Prints value as single-precision floating point number (i.e. float) + * Prints value as single-precision floating point number. * * @ingroup console - * @param val - float to be printed + * @param val - single-precision floating point number to be printed. */ void printsf(float32_t val); /** - * Prints value as double-precision floating point number (i.e. double) + * Prints value as double-precision floating point number. * * @ingroup console - * @param val - float to be printed + * @param val - double-precision floating point number to be printed */ - void printdf(float64_t val); + void printdf(float64_t val);. /** - * Prints value as quadruple-precision floating point number (i.e. long double) + * Prints value as quadruple-precision floating point number. * * @ingroup console - * @param val - a pointer to the long double to be printed + * @param val - a pointer to the quadruple-precision floating point number to be printed */ void printqf(legacy_ptr val); @@ -761,7 +763,7 @@ namespace webassembly { * Prints a 64 bit names as base32 encoded string * * @ingroup console - * @param data - Hex name to be printed + * @param data - Hex name to be printed. */ void printhex(legacy_span data); @@ -798,7 +800,7 @@ namespace webassembly { * Remove a record inside a primary 64-bit integer index table. * * @ingroup database primary-index - * @param itr - the terator to the table row to remove. + * @param itr - the iterator to the table row to remove. * * @pre `itr` points to an existing table row in the tab. */ @@ -1521,7 +1523,7 @@ namespace webassembly { int32_t db_idx_long_double_find_secondary(uint64_t code, uint64_t scope, uint64_t table, legacy_ptr secondary, legacy_ptr primary); /** - * Find a table row in a quadruple double-precision floating-point index table by primary key. + * Find a table row in a secondary double-precision floating-point index table by primary key. * * @ingroup database long-double-secondary-index * @param code - the name of the owner of the table. @@ -1637,7 +1639,7 @@ namespace webassembly { /** * Check the existence of a key. * If the key doesn't exist, it returns false, clears the temporary data buffer and sets *value_size to 0. - * If the key does exist, it returns true, stores the value into the temporary data buffer, + * If the key does exist, it returns true, stores the value into the temporary data buffer * and sets *value_size to the value size. * Use kv_get_data to retrieve the value. * @@ -1658,7 +1660,7 @@ namespace webassembly { * @param offset - position from where to start reading the value from the temporary buffer. * @param[out] data - span where the result value will be stored. * - * @return number of bytes written in data + * @return number of bytes written in data. */ uint32_t kv_get_data(uint64_t, uint32_t offset, span data); @@ -1683,7 +1685,7 @@ namespace webassembly { * Destroy a kv iterator. * * @ingroup kv-database - * @param itr - the iterator to destroy. + * @param itr - the kv iterator to destroy. */ void kv_it_destroy(uint32_t itr); @@ -1740,8 +1742,8 @@ namespace webassembly { * * @ingroup kv-database * @param itr - the iterator we want to move. - * @param [out] found_key_size - size of the result key in the new position. - * @param [out] found_value_size - size of the result value in the new position. + * @param[out] found_key_size - size of the result key in the new position. + * @param[out] found_value_size - size of the result value in the new position. * * @return the status of the iterator. */ @@ -1752,8 +1754,8 @@ namespace webassembly { * * @ingroup kv-database * @param itr - the iterator we want to move - * @param [out] found_key_size - size of the result key in the new position. - * @param [out] found_value_size - size of the result value in the new position. + * @param[out] found_key_size - size of the result key in the new position. + * @param[out] found_value_size - size of the result value in the new position. * * @return the status of the iterator. */ @@ -1763,12 +1765,14 @@ namespace webassembly { * Find the least non-deleted key which is >= the provided key. * * @ingroup kv-database - * @param itr + * @param itr - the kv iterator. * @param key - the key we want to query - * @param found_key_size - size of the result found key - * @param found_value_size - size of the result found value + * @param[out] found_key_size - size of the result found key + * @param[out] found_value_size - size of the result found value * * @return the status of the iterator. + * @post if a key is found, the new status is iterator_ok. If not found, the new status is iterator_end. kv_it_lower_bound never returns iterator_erased. + * @post the size of the key and the size of the value at the iterator's new position, or zero if the iterator is at end, will be written to found_key_size and found_value_size. */ int32_t kv_it_lower_bound(uint32_t itr, span key, uint32_t* found_key_size, uint32_t* found_value_size); @@ -1778,8 +1782,8 @@ namespace webassembly { * @ingroup kv-database * @param itr - the kv iterator. * @param offset - position from where to start reading. - * @param dest - where the data will reside. - * @param [out] actual_size - size of the key + * @param[out] dest - where the data will reside. + * @param[out] actual_size - size of the key * * @return the status of the iterator passed as a parameter. */ @@ -1791,8 +1795,8 @@ namespace webassembly { * @ingroup kv-database * @param itr - the iterator of the object we want to get the value. * @param offset - position from where to start reading. - * @param dest - where the data will reside. - * @param [out] actual_size - size of the value. + * @param[out] dest - where the value will reside. + * @param[out] actual_size - size of the value. * * @return the status of the iterator passed as a parameter. */ @@ -1826,7 +1830,7 @@ namespace webassembly { * @ingroup transaction * @param sender_id - account name of the sender of this deferred transaction. * @param payer - account name responsible for paying the RAM for this deferred transaction. - * @param data - the packed transaction to be deferred + * @param data - the packed transaction to be deferred. * @param replace_existing - if true, it will replace an existing transaction. */ void send_deferred(legacy_ptr sender_id, account_name payer, legacy_span data, uint32_t replace_existing); @@ -1835,48 +1839,46 @@ namespace webassembly { * Cancels a deferred transaction. * * @ingroup transaction - * @param val - The id of the sender + * @param val - The id of the sender. * - * @retval false if transaction was not found - * @retval true if transaction was canceled + * @retval false if transaction was not found. + * @retval true if transaction was canceled. */ bool cancel_deferred(legacy_ptr val); - // context-free transaction api - /** * Access a copy of the currently executing transaction. * - * @ingroup transaction + * @ingroup context-free-transaction * @param[out] data - the currently executing transaction (packed). * - * @retval false if transaction was not found - * @retval true if transaction was canceled + * @retval false if transaction was not found. + * @retval true if transaction was canceled. */ int32_t read_transaction(legacy_span data) const; /** * Gets the size of the currently executing transaction. * - * @ingroup transaction + * @ingroup context-free-transaction * - * @return size of the currently executing transaction + * @return size of the currently executing transaction. */ int32_t transaction_size() const; /** * Gets the expiration of the currently executing transaction. * - * @ingroup transaction + * @ingroup context-free-transaction * - * @return expiration of the currently executing transaction in seconds since Unix epoch + * @return expiration of the currently executing transaction in seconds since Unix epoch. */ int32_t expiration() const; /** * Gets the block number used for TAPOS on the currently executing transaction. * - * @ingroup transaction + * @ingroup context-free-transaction * * @return block number used for TAPOS on the currently executing transaction. */ @@ -1885,7 +1887,7 @@ namespace webassembly { /** * Gets the block prefix used for TAPOS on the currently executing transaction. * - * @ingroup transaction + * @ingroup context-free-transaction * * @return block prefix used for TAPOS on the currently executing transaction. */ @@ -1894,7 +1896,7 @@ namespace webassembly { /** * Retrieve the indicated action from the active transaction. * - * @ingroup transaction + * @ingroup context-free-transaction * * @param type - 0 for context free action, 1 for action. * @param index - the index of the requested action. From 5232f1b434176e9307cfae4529280a9a4cd2f52d Mon Sep 17 00:00:00 2001 From: Victor Camacho Date: Fri, 18 Sep 2020 08:38:01 -0400 Subject: [PATCH 10/14] document some host functions --- libraries/chain/include/eosio/chain/webassembly/interface.hpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/libraries/chain/include/eosio/chain/webassembly/interface.hpp b/libraries/chain/include/eosio/chain/webassembly/interface.hpp index 2637af84d9d..7bba9656d85 100644 --- a/libraries/chain/include/eosio/chain/webassembly/interface.hpp +++ b/libraries/chain/include/eosio/chain/webassembly/interface.hpp @@ -741,7 +741,7 @@ namespace webassembly { * @ingroup console * @param val - double-precision floating point number to be printed */ - void printdf(float64_t val);. + void printdf(float64_t val); /** * Prints value as quadruple-precision floating point number. From 0c9b57e677ba30782ae667c5f5ed563ea0bdabae Mon Sep 17 00:00:00 2001 From: Victor Camacho Date: Mon, 21 Sep 2020 19:13:54 -0400 Subject: [PATCH 11/14] adding doxybook --- docs.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs.json b/docs.json index 16195c6fc37..a2a61c317f6 100644 --- a/docs.json +++ b/docs.json @@ -68,6 +68,10 @@ }, "disable_default_filters" :true, "filters" : [] + }, + { + "name": "doxybook", + "options": {} } ] } From eac4eacca1d18048c337bfc7878de58939d15509 Mon Sep 17 00:00:00 2001 From: Victor Camacho Date: Mon, 21 Sep 2020 19:22:06 -0400 Subject: [PATCH 12/14] add some missing * --- libraries/chain/include/eosio/chain/webassembly/interface.hpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/libraries/chain/include/eosio/chain/webassembly/interface.hpp b/libraries/chain/include/eosio/chain/webassembly/interface.hpp index 7bba9656d85..6b1648253e3 100644 --- a/libraries/chain/include/eosio/chain/webassembly/interface.hpp +++ b/libraries/chain/include/eosio/chain/webassembly/interface.hpp @@ -58,7 +58,7 @@ namespace webassembly { */ void preactivate_feature(legacy_ptr feature_digest); - /* + /** * Set the resource limits of an account. * * @ingroup privileged @@ -70,7 +70,7 @@ namespace webassembly { */ void set_resource_limits(account_name account, int64_t ram_bytes, int64_t net_weight, int64_t cpu_weight); - /* + /** * Get the resource limits of an account * * @ingroup privileged From 936bb7cb8d5c633c88b1f8c5414de2becefd23e4 Mon Sep 17 00:00:00 2001 From: Victor Camacho Date: Tue, 22 Sep 2020 16:35:04 -0400 Subject: [PATCH 13/14] documentation of host functions - some wording correction --- .../include/eosio/chain/webassembly/interface.hpp | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/libraries/chain/include/eosio/chain/webassembly/interface.hpp b/libraries/chain/include/eosio/chain/webassembly/interface.hpp index 6b1648253e3..9dd9007047a 100644 --- a/libraries/chain/include/eosio/chain/webassembly/interface.hpp +++ b/libraries/chain/include/eosio/chain/webassembly/interface.hpp @@ -602,14 +602,14 @@ namespace webassembly { name get_sender() const; /** - * Aborts processing of this action and unwinds all pending changes if the test condition is true. + * Aborts processing of this action and unwinds all pending changes. * * @ingroup context-free */ void abort() const; /** - * Aborts processing of this action if the test condition is true. + * Aborts processing of this action if the test condition is false. * * @ingroup context-free * @param condition - test condition. @@ -618,7 +618,7 @@ namespace webassembly { void eosio_assert(bool condition, null_terminated_ptr msg) const; /** - * Aborts processing of this action if the test condition is true. + * Aborts processing of this action if the test condition is false. * * @ingroup context-free * @param condition - test condition. @@ -627,7 +627,7 @@ namespace webassembly { void eosio_assert_message(bool condition, legacy_span msg) const; /** - * Aborts processing of this action if the test condition is true. + * Aborts processing of this action if the test condition is false. * It can be used to provide an error code rather than a message string on assertion checks. * If the assertion fails, the provided error code will be made available through the exception message. * @@ -638,7 +638,7 @@ namespace webassembly { void eosio_assert_code(bool condition, uint64_t error_code) const; /** - * This method will abort execution of wasm without failing the contract + * This method will abort execution of wasm without failing the contract. * * @ingroup context-free * @param code - the exit code @@ -646,7 +646,7 @@ namespace webassembly { void eosio_exit(int32_t code) const; /** - * Copy up to length bytes of current action data to the specified location + * Copy up to length bytes of the current action data to the specified location. * * @ingroup action * @param memory - a pointer where up to length bytes of the current action data will be copied. @@ -656,7 +656,7 @@ namespace webassembly { int32_t read_action_data(legacy_span memory) const; /** - * Get the length of the current action's data field. This method is useful for dynamically sized actions + * Get the length of the current action's data field. This method is useful for dynamically sized actions. * * @ingroup action * @return the length of the current action's data field From 67c4835acf2f11293a85cb6d487d5607a0733f6b Mon Sep 17 00:00:00 2001 From: Victor Camacho Date: Tue, 22 Sep 2020 19:10:00 -0400 Subject: [PATCH 14/14] document host functions - change table to use codeblocks --- libraries/chain/include/eosio/chain/webassembly/interface.hpp | 2 ++ 1 file changed, 2 insertions(+) diff --git a/libraries/chain/include/eosio/chain/webassembly/interface.hpp b/libraries/chain/include/eosio/chain/webassembly/interface.hpp index 9dd9007047a..f018b123a44 100644 --- a/libraries/chain/include/eosio/chain/webassembly/interface.hpp +++ b/libraries/chain/include/eosio/chain/webassembly/interface.hpp @@ -256,6 +256,7 @@ namespace webassembly { /** * Gets the maximum key size, maximum value size, and maximum iterators of a kv database and returns the size of the data. * The kv parameters are encoded as 16 bytes, representing four 32-bit little-endian values. + * ``` * +-------+---------------+---------------+---------------+---------------+ * | byte | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 |10 |11 |12 |13 |14 |15 | * +-------+---------------+---------------+---------------+---------------+ @@ -263,6 +264,7 @@ namespace webassembly { * +-------+---------------+---------------+---------------+---------------+ * | type | 0 | 32-bits LE | 32-bits LE | 32-bits LE | * +-------+---------------+---------------+---------------+---------------+ + * ``` * * @ingroup privileged * @param[out] packed_kv_parameters - the buffer containing the packed kv parameters.