Skip to content

Commit

Permalink
add "how many tokens will attached gas cost" box
Browse files Browse the repository at this point in the history
  • Loading branch information
chadoh committed Aug 6, 2020
1 parent a32b680 commit c3106fc
Showing 1 changed file with 13 additions and 1 deletion.
14 changes: 13 additions & 1 deletion docs/concepts/gas.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,12 +148,24 @@ If you're coming from Ethereum, you may be used to the idea of paying a higher g

For basic operations like "transfer funds," you can't specify an amount to attach. The gas needed is easy to calculate ahead of time, so it's automatically attached for you. (Check it: [`near-cli`](https://github.com/near/near-cli) has a `send` command, which accepts no `gas` parameter; [`near-api-js`](https://github.com/near/near-api-js) has a [`sendTokens`](https://near.github.io/near-api-js/classes/_near_.near.html#sendtokens) function which accepts no `gas` argument.) As shown in the tables above, these operations are cheap, so you probably won't even notice the slight reduction in your account's balance.

Function calls are more complex, and you can attach an explicit amount of gas to these transactions, up to a [maximum value](https://github.com/nearprotocol/nearcore/blob/c162dc3ffc8ccb871324994e58bf50fe084b980d/neard/res/mainnet_genesis.json#L193) of 3⨉10¹⁴ gas units. As a reminder, these will be multiplied by the gas price, making this maximum attached gas correspond to a final gas fee of `3⨉10¹⁴ ⨉ 10⁸ = 3⨉10²²` or 0.03Ⓝ at minimum gas price. Here's how you would override the default attached gas with [`near-cli`](https://github.com/near/near-cli):
Function calls are more complex, and you can attach an explicit amount of gas to these transactions, up to a [maximum value](https://github.com/nearprotocol/nearcore/blob/c162dc3ffc8ccb871324994e58bf50fe084b980d/neard/res/mainnet_genesis.json#L193) of 3⨉10¹⁴ gas units. Here's how you would override the default attached gas with [`near-cli`](https://github.com/near/near-cli):

near call myContract.testnet myFunction "{ \"arg1\": \"val1\" }" --gas=300000000000000

And in [`near-api-js`](https://github.com/near/near-api-js), you can also specify an explicit amount of gas units to attach when calling a change method; see [example here](https://github.com/near-examples/guest-book/blob/ceb2a39e53351b4ffc21d01987e2b0b21d633fa7/src/App.js#L29).

<blockquote class="warning">
<strong>How many tokens will these units cost?</strong><br><br>

Note that you are greenlighting a maximum number of gas _units_, not a number of NEAR tokens or yoctoNEAR.

These units will be multiplied by the gas price at the block in which they're processed. If the function call makes cross-contract calls, then separate parts of the function will be processed in different blocks, and could use different gas prices. At a minimum, the function will take two blocks to complete, as explained in [the blue box above](#the-cost-of-common-actions).

Assuming the system rests at minimum gas price of 100 million yoctoNEAR during the total operation, a maximum attached gas of 3⨉10¹⁴ would seem to allow a maximum expenditure of 3⨉10²² yN. However, there's also a pessimistic multiplier of about 6.4 to [prevent shard congestion](https://github.com/nearprotocol/NEPs/issues/67).

Multiplying all three of these numbers, we find that maximum attached gas units allow about 0.2Ⓝ to be spent on the operation if gas prices stay at their minimum. If gas prices are higher or increase during the operation, this charge could be even higher.
</blockquote>


## Attach extra gas; get refunded!

Expand Down

0 comments on commit c3106fc

Please sign in to comment.