nep-0264.md

NEP	Title	Authors	Status	DiscussionsTo	Type	Version	Created	LastUpdated
264	Utilization of unspent gas for promise function calls	Austin Abell <austinabell8@gmail.com>	Final	#264	Protocol	1.0.0	2021-09-30	2022-05-26

Summary

This proposal is to introduce a new host function on the NEAR runtime that allows for scheduling cross-contract function calls using a percentage/weight of the remaining gas in addition to the statically defined amount. This will enable async promise execution to use the remaining gas more efficiently by utilizing unspent gas from the current transaction.

Motivation

We are proposing this to be able to utilize gas more efficiently but also to improve the devX of cross-contract calls. Currently, developers must guess how much gas will remain after the current transaction finishes and if this value is too little, the transaction will fail, and if it is too large, gas will be wasted. Therefore, these cross-contract calls need a reasonable default of splitting unused gas efficiently for basic cases without sacrificing the ability to configure the gas amount attached at a granular level. Currently, gas is allocated very inefficiently, requiring more prepaid gas or failed transactions when the allocations are imprecise.

Guide-level explanation

This host function is similar to promise_batch_action_function_call, except with an additional parameter that lets you specify how much of the excess gas should be attached to the function call. This parameter is a weight value that determines how much of the excess gas is attached to each function.

So, for example, if there is 40 gas leftover and three function calls that select weights of 1, 5, and 2, the runtime will add 5, 25, and 10 gas to each function call. A developer can specify whether they want to attach a fixed amount of gas, a weight of remaining gas, or both. If at least one function call uses a weight of remaining gas, then all excess gas will be attached to future calls. This proposal allows developers the ability to utilize prepaid gas more efficiently than currently possible.

Reference-level explanation

This host function would need to be implemented in nearcore and parallel promise_batch_action_function_call. Most details of these functions will be consistent, except that there will be additional bookkeeping for keeping track of which functions specified a weight for unused gas. This will not affect or replace any existing host functions, but this will likely require a slightly higher gas cost than the original promise_batch_action_function_call host function due to this additional overhead.

This host function definition would look like this (as a Rust consumer):

    /// Appends `FunctionCall` action to the batch of actions for the given promise pointed by
    /// `promise_idx`. This function allows not specifying a specific gas value and allowing the
    /// runtime to assign remaining gas based on a weight.
    ///
    /// # Gas
    ///
    /// Gas can be specified using a static amount, a weight of remaining prepaid gas, or a mixture
    /// of both. To omit a static gas amount, `0` can be passed for the `gas` parameter.
    /// To omit assigning remaining gas, `0` can be passed as the `gas_weight` parameter.
    ///
    /// The gas weight parameter works as the following:
    ///
    /// All unused prepaid gas from the current function call is split among all function calls
    /// which supply this gas weight. The amount attached to each respective call depends on the
    /// value of the weight.
    ///
    /// For example, if 40 gas is leftover from the current method call and three functions specify
    /// the weights 1, 5, 2 then 5, 25, 10 gas will be added to each function call respectively,
    /// using up all remaining available gas. Any remaining gas will be allocated to the last
    /// function call.
    ///
    /// # Errors
    ///
    /// <...Ommitted previous errors as they do not change>
    /// - If `0` is passed for both `gas` and `gas_weight` parameters
    pub fn promise_batch_action_function_call_weight(
        promise_index: u64,
        method_name_len: u64,
        method_name_ptr: u64,
        arguments_len: u64,
        arguments_ptr: u64,
        amount_ptr: u64,
        gas: u64,
        gas_weight: u64,
    );

The only difference from the existing API is gas_weight added as another parameter, as an unsigned 64-bit integer.

As for calculations, the remaining gas at the end of the transaction can be floor divided by the sum of all the weights tracked. Then, after getting this value, just attach that value multiplied by the weight gas to each function call action.

For example, if there are three weights, a, b, c:

weight_sum = a + b + c
a_gas += remaining_gas * a / weight_sum
b_gas += remaining_gas * b / weight_sum
c_gas += remaining_gas * c / weight_sum

Any remaining gas that is not allocated to any of these function calls will be attached to the last function call scheduled.

SDK changes

This protocol change will allow cross-contract calls to provide a fixed amount of gas and/or adjust the weight of unused gas to use. If neither is provided, it will default to using a weight of 1 for each and no static amount of gas. If no function modifies this weight, the runtime will split the unused gas evenly among all function calls.

Currently, the API for a cross-contract call looks like:

let contract_account_id: AccountId = todo!();
ext::some_method(/* parameters */, contract_account_id, 0 /* deposit amount */, 5_000_000_000_000 /* static amount of gas to attach */)

When the intended API should not require thinking about how much gas to attach by default, the API will look something like what's shown in this PR, which can look like the following:

cross_contract::ext(contract_account_id)
 	// Optional config
	.with_attached_deposit(1 /* default deposit of 0 */)
 	.with_static_gas(Gas(5_000_000_000_000) /* default of 0 */)
 	.with_unused_gas_weight(2 /* default 1 */)

 	// Then call any method to schedule the function call
 	.some_method(/* parameters */)

At a basic level, a developer has only to include the parameters for the function call and specify the account id of the contract being called. Currently, only the amount can be optional because there is no way to set a reasonable default for the amount of gas to use for each function call.

Drawbacks

• Complexity in refactoring to handle assigning remaining gas at the end of a transaction
• Complexity in extra calculations for assigning gas will make the host function slightly more expensive than the base one. It is not easy to create an API on the SDK level that can decide which host function to call if dynamic gas assigning is needed or not. If both are used, the size of the wasm binary is trivially larger by including both host functions
• Adds another host function to the runtime, which can probably never be removed
• Can be confusing to have both static gas and dynamic unused gas and convey what is happening internally to a developer
• If we start utilizing all prepaid gas, this will likely lead to a higher percentage of prepaid gas usage. This could be an unexpected pattern for users and require them to think about how much gas they are attaching to make sure they only attach what they are willing to spend
  • Since currently, we are refunding a lot of unused gas, this could be a hidden negative side effect
  • Keep in mind that it will also be positive because transactions will generally succeed more often due to gas more efficiently

Rationale and alternatives

Alternative 1 (fraction parameters): The primary alternative is using a numerator and denominator to represent a fraction instead of a weight. This alternative would be equivalent to the one listed above except for two u64 additional parameters instead of just the one for weight. I'll list the tradeoff as pros and cons:

Pros:

• Can under-utilize the gas for the current transaction to limit gas allowed for certain functions
• This could take responsibility away from DApp users because they would not have to worry less about attaching too much prepaid gas
• Thinking in terms of fractions may be more intuitive for some developers
• Might future proof better if we ever need this ability in the future, want to minimize the number of host functions created at all costs

Cons:

• More complicated logic/edge cases to handle to make sure the percentages don't sum to greater than 100% (or adjusting if they do)
• Precision loss from dividing integers may lead to unexpected results
  • To get closer to expected, we could use floats for the division, but this gets messy
• API for specifying a fraction would be messy (need to specify two values rather than just optionally one)
• There isn't a good default for this. Unless there is a special value that indicates a pool of function calls that will split the remaining equally, but this defeats the purpose of this alternative completely
• Slightly larger API (only one u64, can probably safely ignore this point)

Alternative 2 (handle within contract/SDK): The other alternative is to handle all of this logic on the contract side, as seen by this PR. This is much less feasible/accurate because there is only so much information available within the runtime, and gas costs and internal functionality may not always be the same. As discussed on the respective issue, this alternative seems to be very infeasible.

Pros:

• No protocol change is needed
• Can still have improved API as with protocol change

Cons:

• Additional bloat to every contract, even ones that don't use the pattern (~5kb in PoC, even with simple estimation logic)
• Still inaccurate gas estimations, because at the point of calculation, we cannot know how much gas will be used for assigning gas values as well as gas consumed after the transaction ends
  • This leads to either underutilizing or having transactions fail when using too much gas if trying to estimate how much gas will be left
• Prone to breaking existing contracts on protocol changes that affect gas usage or logic of runtime

Unresolved questions

What needs to be addressed before this gets merged: - How much refactoring exactly is needed to handle this pattern? - Can we keep a queue of receipt and action indices with their respective weights and update their gas values after the current method is executed? Is there a cleaner way to handle this while keeping order? - Do we want to attach the gas lost due to precision on division to any function?

• The remaining gas is now attached to the last function call

What would be addressed in future independently of the solution:

• How many users would expect the ability to refund part of the gas after the initial transaction? (is this worth considering the API difference of using fractions rather than weights)
• Will weights be an intuitive experience for developers?

Future possibilities

The future change that would extend from this being implemented is a much cleaner API for the SDKs. As mentioned previously in the alternatives section, the API changes from the changes tested on the SDK will remain, but without the overhead from implementing this on the contract level. Thus, not only can this be implemented in Rust, but it will also allow a consistent API for existing and future SDK languages to build on.

The primary benefit for SDKs is that it removes the need to specify gas when making cross-contract calls explicitly. Currently, there is no easy way of knowing how many function calls will be made to split prepaid gas without a decent amount of overhead. Even if the developer does this, it's impossible to know how much gas will remain after the transaction from inside the contract. Having this host function available will simplify the DevX for contract developers and make the contracts use gas more efficiently.