Skip to content

Commit 53c46b6

Browse files
DariuszDeptaDariuszDepta
committed
Prepared initial version.
0 parents  commit 53c46b6

File tree

15 files changed

+466
-0
lines changed

15 files changed

+466
-0
lines changed

‎.github/workflows/deploy.yml‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
name: Deploy
2+
3+
on:
4+
# Runs on pushes targeting the `main` branch.
5+
push:
6+
branches: [main]
7+
8+
# Allows to run this workflow manually from the Actions tab.
9+
workflow_dispatch:
10+
11+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
18+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
19+
concurrency:
20+
group: pages
21+
cancel-in-progress: false
22+
23+
jobs:
24+
25+
# Build job
26+
build:
27+
runs-on: ubuntu-latest
28+
name: Build
29+
steps:
30+
- name: Checkout
31+
uses: actions/checkout@v5
32+
with:
33+
fetch-depth: 0 # Not needed if lastUpdated is not enabled
34+
35+
- name: Setup Node
36+
uses: actions/setup-node@v5
37+
with:
38+
node-version: 20
39+
cache: npm
40+
41+
- name: Setup Pages
42+
uses: actions/configure-pages@v5
43+
44+
- name: Install dependencies
45+
run: npm ci
46+
47+
- name: Build with VitePress
48+
run: npm run docs:build
49+
50+
- name: Upload artifact
51+
uses: actions/upload-pages-artifact@v3
52+
with:
53+
path: .vitepress/dist
54+
55+
# Deployment job
56+
deploy:
57+
environment:
58+
name: github-pages
59+
url: ${{ steps.deployment.outputs.page_url }}
60+
needs: build
61+
runs-on: ubuntu-latest
62+
name: Deploy
63+
steps:
64+
- name: Deploy to GitHub Pages
65+
id: deployment
66+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
node_modules
2+
.idea/
3+
.vitepress/dist
4+
.vitepress/cache

‎.vitepress/config.mts‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
import {withMermaid} from "vitepress-plugin-mermaid";
2+
3+
export default withMermaid({
4+
lang: 'en-US',
5+
base: '/',
6+
title: "CosmWasm",
7+
description: "User guide for CosmWasm smart contract developers",
8+
head: [['link', {rel: 'icon', href: '/cosmwasm-small.svg'}]],
9+
themeConfig: {
10+
logo: '/cosmwasm-small.svg',
11+
nav: [
12+
{
13+
text: 'Guide',
14+
items: [
15+
{text: 'Welcome', link: '/guide/welcome'},
16+
],
17+
18+
},
19+
],
20+
sidebar: [
21+
{
22+
text: 'Guide',
23+
items: [
24+
{
25+
text: 'Welcome', link: '/guide/welcome'
26+
},
27+
{
28+
text: 'CosmWasm Core',
29+
link: '/guide/cosmwasm-core/introduction',
30+
collapsed: true,
31+
items: [
32+
{
33+
text: 'Architecture',
34+
link: '/guide/cosmwasm-core/architecture/architecture',
35+
collapsed: true,
36+
items: [
37+
{text: 'Gas', link: '/guide/cosmwasm-core/architecture/gas'},
38+
]
39+
},
40+
]
41+
},
42+
],
43+
},
44+
],
45+
search: {
46+
provider: 'local'
47+
}
48+
},
49+
mermaid: {
50+
// Refer https://mermaid.js.org/config/setup/modules/mermaidAPI.html#mermaidapi-configuration-defaults for options.
51+
},
52+
markdown: {
53+
math: true
54+
},
55+
srcDir: "pages"
56+
})

‎.vitepress/theme/index.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
import type { Theme } from 'vitepress'
2+
import DefaultTheme from 'vitepress/theme'
3+
import './style.css'
4+
5+
export default {
6+
extends: DefaultTheme,
7+
} satisfies Theme

‎.vitepress/theme/style.css‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
:root {
2+
--dt-light-background: #A855F7;
3+
--dt-dark-background: #334155;
4+
--vp-home-hero-name-color: transparent;
5+
--vp-home-hero-name-background: -webkit-linear-gradient(120deg, var(--dt-dark-background), var(--dt-light-background));
6+
}

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# CosmWasm User Guide
2+
3+
### https://cosmwasm.github.io

‎Taskfile.yml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
version: '3'
2+
3+
silent: true
4+
5+
tasks:
6+
7+
clean:
8+
desc: Clean artifacts
9+
cmds:
10+
- cmd: rm -rf .vitepress/cache
11+
- cmd: rm -rf .vitepress/dist
12+
13+
serve:
14+
desc: Start server locally
15+
cmds:
16+
- task: clean
17+
- cmd: npm run docs:dev
18+
19+
build:
20+
desc: Build documentation
21+
cmds:
22+
- task: clean
23+
- cmd: npm run docs:build
24+
25+
preview:
26+
desc: Preview documentation
27+
cmds:
28+
- task: clean
29+
- cmd: npm run docs:build
30+
- cmd: npm run docs:preview

‎package.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"devDependencies": {
3+
"markdown-it-mathjax3": "^4.3.2",
4+
"mermaid": "^11.12.0",
5+
"vitepress": "^1.6.4",
6+
"vitepress-plugin-mermaid": "^2.0.17",
7+
"vue": "^3.5.22"
8+
},
9+
"scripts": {
10+
"docs:dev": "vitepress dev",
11+
"docs:build": "vitepress build",
12+
"docs:preview": "vitepress preview"
13+
},
14+
"dependencies": {
15+
"npm-check-updates": "^18.3.0"
16+
}
17+
}

‎pages/guide/cosmwasm-core/architecture/architecture.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
# Architecture

‎pages/guide/cosmwasm-core/architecture/gas.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
[#1599]: https://github.com/CosmWasm/cosmwasm/pull/1599
2+
[JSON numbers]: https://www.json.org/
3+
[default-gas-multiplier]: https://github.com/CosmWasm/wasmd/blob/04cb6e5408cc54c27247b0b327dfa99769d5103c/x/wasm/types/gas_register.go#L34
4+
[near-gas]: https://docs.near.org/concepts/protocol/gas
5+
[#1120]: https://github.com/CosmWasm/cosmwasm/pull/1120
6+
7+
# Gas
8+
9+
Gas is a way to measure computational expense of a smart contract execution, including CPU time and
10+
storage cost. Its unit is 1, i.e. you can think of it as countable points. Gas consumption is
11+
deterministic, so executing the same thing costs the same amount of gas across all hardware and
12+
operating systems.
13+
14+
## CosmWasm gas vs. Cosmos SDK gas
15+
16+
CosmWasm charges gas for Wasm operations, calls to host functions and calls to the Cosmos SDK.
17+
_**CosmWasm gas**_ is different from _**Cosmos SDK gas**_ as the numbers here are much larger.
18+
Since we charge gas for arbitrary user defined operations, we need to charge each Wasm operation
19+
individually and cannot group larger tasks together. As a result, the gas values become much larger
20+
than in Cosmos SDK even for very fast executions. There is a [multiplier][default-gas-multiplier]
21+
to translate between _**CosmWasm gas**_ and _**Cosmos SDK**_ gas.
22+
It was measured and set to 100 a while ago and can be adjusted when necessary.
23+
24+
## CosmWasm gas pricing
25+
26+
For CosmWasm gas, the target gas consumption is 1 Teragas ($10^{12}$ gas) per second. This idea is
27+
[inspired by NEAR][near-gas] and we encourage you to read their excellent docs on that topic.
28+
29+
In order to meet this target, we execute Argon2 in a test contract ([#1120]). This is a CPU and
30+
memory intense job that does not call out into the host. At a constant gas cost per operation of 1
31+
(pre CosmWasm 1.0), this consumed 96837752 gas and took 15ms on our CI system. The ideal cost per
32+
operation for this system is `10^12 / (96837752 / (15 / 1000))`: 154. This is rounded to 150 for
33+
simplicity.
34+
35+
CosmWasm 2.1 update: All gas values were re-evaluated and adjusted to meet the 1 Teragas/second
36+
target mentioned above. A rerun of the Argon2 test contract consumed 5270718300 gas with the
37+
previous cost of 150, so the operation count was `5270718300 / 150 = 35138122`. This took 6ms on our
38+
benchmark server, so the new cost per operation is `10^12 / (35138122 / (6 / 1000))`: 171. This is
39+
rounded to 170 for simplicity.
40+
41+
Benchmarking system:
42+
43+
- CPU: Intel(R) Core(TM) i7-6700 CPU @ 3.40GHz (4 cores, 8 threads)
44+
- RAM: 32GB DDR4 2133 MHz
45+
46+
Each machine is different, we know that. But the above target helps us in multiple ways:
47+
48+
1. Develop an intuition what it means to burn X gas or how much gas can be used if a block should be
49+
executable in e.g. 1 second.
50+
2. Have a target for adjustments, e.g. when the Wasm runtime becomes faster or slower.
51+
3. Allow pricing of calls that are not executed in Wasm, such as crypto APIs.
52+
4. Find significant over- or underpricing.
53+
54+
## Gas overflow potential
55+
56+
CosmWasm gas aims for Teragas/second, i.e. the 64-bit unsigned integer range exceeds
57+
after 18 million seconds (≈5000 hours)<sup>1)</sup>. Assuming a maximal supported block execution
58+
time of 30 seconds, the gas price has to be over-priced by a factor of 614891 (614891 Teragas/second)
59+
in order to exceed the 64-bit unsigned integer range<sup>2)</sup>. Since serious over- or underpricing
60+
is considered a bug, using 64-bit unsigned integer for gas measurements is **considered safe**.
61+
62+
Cosmos SDK gas uses values that are smaller by a factor of 150, so those don't overflow as well.
63+
Since no Cosmos SDK gas values are processed inside of this repository, this is not our main
64+
concern. However, it's good to know that we can safely pass them in 64-bit fields, as long as the
65+
full range is supported. This is the case for the C API as well as [JSON numbers] as long as both
66+
sides support integers in their JSON implementation. Go and Rust do that while many other
67+
implementations don't support integers, and convert them to IEEE-754 doubles, which has a safe
68+
integer range up to about 53 bit (e.g. JavaScript and jq).
69+
70+
<sup>1)</sup> $\frac{2^{64} - 1}{10^{12}} \approx 18446744s$, ${18446744 \over 3600} \approx 5124 h$
71+
72+
<sup>2)</sup> $\frac{2^{64} - 1}{30 \times 10^{12}} \approx 614891$
73+
74+
## Changes from version 1.x to 2.0 of CosmWasm
75+
76+
In all versions before 2.0, the gas values were bigger by a factor of **1000**.
77+
There is no need to have them this big and in order to reduce the risk of
78+
overflow, the gas values were lowered in this issue [#1599].
79+
80+
Below is a breakdown of what this change entails:
81+
82+
| | CosmWasm 1.x | CosmWasm 2.x |
83+
|-----------------------------------------------------|:---------------------:|:-------------------------:|
84+
| **Cost target** | 1 Teragas/millisecond | 1 Teragas/second |
85+
| **Exceeds 64-bit unsigned<br/>integer range after** | 5 hours | 5124 hours<br/>≈ 213 days |
86+
| **Cost per Wasm operation** | 150.000 | 150 |
87+
| **Multiplier** | 140.000.000 | 140.000 |

0 commit comments

Comments
 (0)