From 999529093d884bbfed03d9b6070977fcf4c9ed57 Mon Sep 17 00:00:00 2001 From: Chad Ostrowski <221614+chadoh@users.noreply.github.com> Date: Wed, 5 Aug 2020 18:14:03 -0400 Subject: [PATCH] rework "how do I buy" and "attach extra" sections --- docs/concepts/gas.md | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/docs/concepts/gas.md b/docs/concepts/gas.md index 1ce6761e933..b9f76b3f73c 100644 --- a/docs/concepts/gas.md +++ b/docs/concepts/gas.md @@ -137,21 +137,39 @@ You can expect the network to sit at the minimum gas price most of the time; lea We will have a demonstration of how to do in-depth gas cost estimation soon; [subscribe to this issue](https://github.com/near/devx/issues/253) for updates. Until then, you may want to look at this [example of how to do simulation testing](https://github.com/near-examples/simulation-testing), a powerful way to test your contracts and inspect every aspect of their execution. -## Go ahead and attach too much gas, you'll get refunded -If you're coming from Ethereum, you may be used to the idea of paying extra gas fees to get your transaction processed faster. In NEAR, gas costs are deterministic, and you can't pay extra. +## How do I buy gas? + +You don't directly buy gas; you attach tokens to transactions. + +Calls to NEAR to read data are always free. But when you make a call to add or update data, you have to do so from an account that has some amount of NEAR tokens available in its balance, and these tokens will be attached to pay the gas fee. + +If you're coming from Ethereum, you may be used to the idea of paying a higher gas price to get your transaction processed faster. In NEAR, gas costs are deterministic, and you can't pay extra. + +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¹⁴ yN. Here's how you would override the default attached gas with [`near-cli`](https://github.com/near/near-cli): -For basic operations like "transfer funds" you can't even specify gas amount! The gas is easy to calculate ahead of time and the small amount of tokens necessary are automatically deducted from your account. (Check it: [`near-shell`](https://github.com/near/near-shell) 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.) + near call myContract.testnet myFunction "{ \"arg1\": \"val1\" }" --gas=300000000000000 -But you can attach a maximum amount of gas to a function call (see [near-shell](https://github.com/near/near-shell/blob/46ba4d3f684bd209fcca8f9f1fd56181f0a6648d/commands/call.js#L10) and [near-api-js](https://github.com/near/near-api-js/blob/74c11fcefc01928136a7dc9b7df8a5a108de4414/src/contract.ts#L42)). How can you know how much to attach? You can't! +And in [`near-api-js`](https://github.com/near/near-api-js), given a `contract` that you've instantiated with `new Contract`, you can attach an explicit gas amount when calling a change method on this contract with: -Yes, NEAR's runtime uses [Wasm](https://webassembly.org/) and Wasm runs in browsers, so for NEAR-backed web apps one could create a browser extension to show gas _estimates_. But these would still be estimates and not exact, since the amount of data stored in a contract can affect function call complexity. + contract.myFunction({ arg1: 'val1' }, '300000000000000') + + +## Attach extra gas; get refunded! + +How can you know the exact right amount to attach when you call a function? You can't! + +Gas units are based on computational complexity for a given operation, which can be affected by a smart contract's state. This is hard to predict ahead of time. And gas price is adjusted each block based on how busy the network was during the previous block, which is also hard to predict ahead of time. But good news! * Gas doesn't cost much on NEAR * If you attach more gas than needed, you'll get refunded +This is also true for basic operations. In the previous section we mentioned that these are automatically calculated and attached. In fact, given that the gas price could be adjusted slightly while these operations are being applied (see blue box [above](#the-cost-of-common-actions)), a slight amount extra is attached, and any beyond what's necessary gets refunded. + ---