Skip to content

Commit

Permalink
Merge branch 'master' into restrict-ethereum-address
Browse files Browse the repository at this point in the history
  • Loading branch information
frol authored Nov 16, 2023
2 parents 8a3594f + b9c3d15 commit e6acabc
Show file tree
Hide file tree
Showing 5 changed files with 877 additions and 28 deletions.
5 changes: 4 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Changes to the protocol specification and standards are called NEAR Enhancement
## NEPs

| NEP # | Title | Author | Status |
| ----------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------- | ------ |
| ----------------------------------------------------------------- |------------------------------------------|---------------------------------------------|--------|
| [0001](https://github.com/near/NEPs/blob/master/neps/nep-0001.md) | NEP Purpose and Guidelines | @jlogelin | Living |
| [0021](https://github.com/near/NEPs/blob/master/neps/nep-0021.md) | Fungible Token Standard (Deprecated) | @evgenykuzyakov | Final |
| [0141](https://github.com/near/NEPs/blob/master/neps/nep-0141.md) | Fungible Token Standard | @evgenykuzyakov @oysterpack | Final |
Expand All @@ -23,12 +23,15 @@ 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 |
| [0399](https://github.com/near/NEPs/blob/master/neps/nep-0399.md) | Flat Storage | @Longarithm @mzhangmzz | Review |
| [0448](https://github.com/near/NEPs/blob/master/neps/nep-0448.md) | Zero-balance Accounts | @bowenwang1996 | Final |
| [0455](https://github.com/near/NEPs/blob/master/neps/nep-0455.md) | Parameter Compute Costs | @akashin @jakmeier | Final |
| [0514](https://github.com/near/NEPs/blob/master/neps/nep-0514.md) | Fewer Block Producer Seats in `testnet` | @nikurt | Final |


## Specification

Expand Down
26 changes: 13 additions & 13 deletions nep-0000-template.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,11 +58,11 @@ See example above -->

[This technical section is required for Protocol proposals but optional for other categories. A draft implementation should demonstrate a minimal implementation that assists in understanding or implementing this proposal. Explain the design in sufficient detail that:

- Its interaction with other features is clear.
- Where possible, include a Minimum Viable Interface subsection expressing the required behavior and types in a target programming language. (ie. traits and structs for rust, interfaces and classes for javascript, function signatures and structs for c, etc.)
- It is reasonably clear how the feature would be implemented.
- Corner cases are dissected by example.
- For protocol changes: A link to a draft PR on nearcore that shows how it can be integrated in the current code. It should at least solve the key technical challenges.
* Its interaction with other features is clear.
* Where possible, include a Minimum Viable Interface subsection expressing the required behavior and types in a target programming language. (ie. traits and structs for rust, interfaces and classes for javascript, function signatures and structs for c, etc.)
* It is reasonably clear how the feature would be implemented.
* Corner cases are dissected by example.
* For protocol changes: A link to a draft PR on nearcore that shows how it can be integrated in the current code. It should at least solve the key technical challenges.

The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work.]

Expand All @@ -84,15 +84,15 @@ The section should return to the examples given in the previous section, and exp

### Positive

- p1
* p1

### Neutral

- n1
* n1

### Negative

- n1
* n1

### Backwards Compatibility

Expand All @@ -102,9 +102,9 @@ The section should return to the examples given in the previous section, and exp

[Explain any issues that warrant further discussion. Considerations

- What parts of the design do you expect to resolve through the NEP process before this gets merged?
- What parts of the design do you expect to resolve through the implementation of this feature before stabilization?
- What related issues do you consider out of scope for this NEP that could be addressed in the future independently of the solution that comes out of this NEP?]
* What parts of the design do you expect to resolve through the NEP process before this gets merged?
* What parts of the design do you expect to resolve through the implementation of this feature before stabilization?
* What related issues do you consider out of scope for this NEP that could be addressed in the future independently of the solution that comes out of this NEP?]

## Changelog

Expand All @@ -118,8 +118,8 @@ The section should return to the examples given in the previous section, and exp

> List of benefits filled by the Subject Matter Experts while reviewing this version:
- Benefit 1
- Benefit 2
* Benefit 1
* Benefit 2

#### Concerns

Expand Down
36 changes: 22 additions & 14 deletions specs/Proposals/0264-promise_gas_ratio.md → neps/nep-0264.md
Original file line number Diff line number Diff line change
@@ -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 <[email protected]>
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
Expand Down Expand Up @@ -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
Expand All @@ -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 */)
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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.

Expand Down
Loading

0 comments on commit e6acabc

Please sign in to comment.