Skip to content

Commit

Permalink
rework "how do I buy" and "attach extra" sections
Browse files Browse the repository at this point in the history
  • Loading branch information
chadoh committed Aug 5, 2020
1 parent 84a52a8 commit 9995290
Showing 1 changed file with 23 additions and 5 deletions.
28 changes: 23 additions & 5 deletions docs/concepts/gas.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.


---

Expand Down

0 comments on commit 9995290

Please sign in to comment.