From 3cba71bb802f35e2f127bfffc9e7651f406cccc9 Mon Sep 17 00:00:00 2001 From: Chad Ostrowski <221614+chadoh@users.noreply.github.com> Date: Wed, 5 Aug 2020 20:51:21 -0400 Subject: [PATCH] add "how many tokens will attached gas cost" box --- docs/concepts/gas.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/docs/concepts/gas.md b/docs/concepts/gas.md index 4b2419d5c9d..217a0a36eb1 100644 --- a/docs/concepts/gas.md +++ b/docs/concepts/gas.md @@ -148,12 +148,26 @@ 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). +
+How many tokens will these units cost?

+ +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 above the minimum, this charge could be higher. + +What if the gas price is at the minimum during the starting block, but the operation takes several blocks to complete, and subsequent blocks have higher gas prices? Could the charge be more than ~0.2Ⓝ? No. The pessimistic multiplier accounts for this possibility. +
+ ## Attach extra gas; get refunded!