chore: move nep-0264_promise_gas_ratio to NEPs (#506)

README.md

@@ -23,6 +23,7 @@ Changes to the protocol specification and standards are called NEAR Enhancement
 | [0181](https://github.com/near/NEPs/blob/master/neps/nep-0181.md) | Non Fungible Token Enumeration           | @chadoh @thor314                            | Final  |
 | [0199](https://github.com/near/NEPs/blob/master/neps/nep-0199.md) | Non Fungible Token Royalties and Payouts | @thor314 @mattlockyer                       | Final  |
 | [0245](https://github.com/near/NEPs/blob/master/neps/nep-0245.md) | Multi Token Standard                     | @zcstarr @riqi @jriemann @marcos.sun        | Review |
+| [0264](https://github.com/near/NEPs/blob/master/neps/nep-0264.md) | Promise Gas Weights                      | @austinabell                                | Final  |
 | [0297](https://github.com/near/NEPs/blob/master/neps/nep-0297.md) | Events Standard                          | @telezhnaya                                 | Final  |
 | [0330](https://github.com/near/NEPs/blob/master/neps/nep-0330.md) | Source Metadata                          | @BenKurrek                                  | Review |
 | [0366](https://github.com/near/NEPs/blob/master/neps/nep-0366.md) | Meta Transactions                        | @ilblackdragon @e-uleyskiy @fadeevab        | Draft  |

specs/Proposals/0264-promise_gas_ratio.md → neps/nep-0264.md

@@ -1,31 +1,35 @@
-- Proposal Name: `promise_gas_weight`
-- Start Date: 2021-09-30
-- NEP PR: [nearprotocol/neps#264](https://github.com/nearprotocol/neps/pull/264)
-- Issue(s): https://github.com/near/near-sdk-rs/issues/526
+---
+NEP: 264
+Title: Utilization of unspent gas for promise function calls
+Authors: Austin Abell <austinabell8@gmail.com>
+DiscussionsTo: https://github.com/near/NEPs/pull/264
+Status: Approved
+Type: Protocol
+Version: 1.0.0
+Created: 2021-09-30
+LastUpdated: 2022-05-26
+---
 
 # Summary
-[summary]: #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
-[motivation]: #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
-[guide-level-explanation]: #guide-level-explanation
 
 This host function is similar to [`promise_batch_action_function_call`](https://github.com/near/nearcore/blob/7d15bbc996282c8ae8f15b8f49d110fc901b84d8/runtime/near-vm-logic/src/logic.rs#L1526), 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
-[reference-level-explanation]: #reference-level-explanation
 
 This host function would need to be implemented in `nearcore` and parallel [`promise_batch_action_function_call`](https://github.com/near/nearcore/blob/7d15bbc996282c8ae8f15b8f49d110fc901b84d8/runtime/near-vm-logic/src/logic.rs#L1526). 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):
+
 ```rust
     /// 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
@@ -70,7 +74,8 @@ The only difference from the existing API is `gas_weight` added as another param
 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`:
-```
+
+```rust
 weight_sum = a + b + c
 a_gas += remaining_gas * a / weight_sum
 b_gas += remaining_gas * b / weight_sum
@@ -84,6 +89,7 @@ Any remaining gas that is not allocated to any of these function calls will be a
 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:
+
 ```rust
 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 */)
@@ -105,7 +111,6 @@ cross_contract::ext(contract_account_id)
 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
-[drawbacks]: #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
@@ -116,18 +121,19 @@ At a basic level, a developer has only to include the parameters for the functio
   - Keep in mind that it will also be positive because transactions will generally succeed more often due to gas more efficiently
 
 # Rationale and alternatives
-[rationale-and-alternatives]: #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
@@ -139,30 +145,32 @@ 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](https://github.com/near/near-sdk-rs/pull/523). 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](https://github.com/near/near-sdk-rs/issues/526), 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
-[unresolved-questions]: #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
+
+- 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
-[future-possibilities]: #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](https://github.com/near/near-sdk-rs/pull/523) 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.