feat: official documentation

docs/from-go-to-gno.md → docs/explanation/from-go-to-gno.md

@@ -1,3 +1,7 @@
+---
+id: from-go-to-gno
+---
+
 # From Go to Gno
 
 ## Runtime comparison
@@ -69,5 +73,5 @@ TODO
 
 ## See also
 
-- [go-gno-compatibility.md](./go-gno-compatibility.md)
+- [go-gno-compatibility.md](../reference/go-gno-compatibility.md)
 - ["go -> gno" presentation by Zack Scholl](https://github.com/gnolang/workshops/tree/main/presentations/2023-06-26--go-to-gno--schollz)

docs/explanation/gno-language.md

@@ -0,0 +1,33 @@
+---
+id: gno-language
+---
+
+# The Gno Language
+
+Gnolang (Gno) is an interpretation of the widely-used Golang (Go) programming language for blockchain created by Cosmos co-founder Jae Kwon in 2021 to mark a new era in smart contracting. Gno is almost identical to Go, so Go developers can quickly start using it, with minimal effort. For example, Gno comes with blockchain-specific standard libraries, but any code that doesn’t use blockchain-specific logic can run in Go with minimal processing. Libraries that could lead to non-deterministic behaviour when executed by thousands of validators are not available in Gno, such as network access, or determining system time. Otherwise, Gno loads and uses many standard libraries that power Go, so the experience writing code feels very similar to Go's.
+
+Under the hood, the Gno code is parsed into an abstract syntax tree (AST) and the AST itself is used in the interpreter, rather than bytecode as in many virtual machines such as Java, Python, or Wasm. The design aims to make reading & understanding the source code of the GnoVM accessible to any Go programmer. The novel design of the intuitive GnoVM interpreter allows Gno to freeze and resume the program by persisting and loading the memory state automatically. Gno is deterministic, auto-persisted, and auto-Merkle-ized, allowing programs to be succinct, as the programmer doesn’t have to serialize and deserialize objects to persist them into a database (unlike programming applications with the Cosmos SDK).
+
+## How Gno Differs from Go
+
+The composable nature of Go/Gno allows for type-checked interactions between contracts, making Gno.land safer and more powerful, as well as operationally cheaper and faster. Smart contracts on Gno.land are light, simple, more focused, and easily interoperable—a network of interconnected contracts rather than siloed monoliths that limit interactions with other contracts.
+
+## Gno Inherits Go’s Built-in Security Features
+
+Go supports secure programming through exported/non-exported fields, enabling a “least-authority” design. It is easy to create objects and APIs that expose only what should be accessible to callers while hiding what should not be simply by the capitalization of letters, thus allowing a succinct representation of secure logic that can be called by multiple users.
+
+Another major advantage of Go is that the language comes with an ecosystem of great tooling, like the compiler and third-party tools that statically analyze code. Gno inherits these advantages from Go directly to create a smart contract programming language that provides embedding, composability, type-check safety, and garbage collection, helping developers to write secure code relying on the compiler, parser, and interpreter to give warning alerts for common mistakes.
+
+## Gno vs Solidity
+
+The most widely-adopted smart contract language today is Ethereum’s EVM-compatible Solidity. With bytecode built from the ground up and Turing complete, Solidity opened up a world of possibilities for decentralized applications (dApps) and there are currently more than 10 million contracts deployed on Ethereum. However, Solidity provides limited tooling and its EVM has a stack limit and computational inefficiencies.
+
+Solidity is designed for one purpose only (writing smart contracts) and is bound by the limitations of the EVM. In addition, developers have to learn several languages if they want to understand the whole stack or work across different ecosystems. Gno aspires to exceed Solidity on multiple fronts (and other smart contract languages like CosmWasm or Substrate) as every part of the stack is written in Gno. It’s easy for developers to understand the entire system just by studying a relatively small code base.
+
+## Gno Is Essential for the Wider Adoption of Web3
+
+Gno makes imports as easy as they are in web2 with runtime-based imports for seamless dependency flow comprehension, and support for complex structs, beyond primitive types. Gno is ultimately cost-effective as dependencies are loaded once, enabling remote function calls as local, and providing automatic and independent per-realm state persistence.
+
+Using Gno, developers can rapidly accelerate application development and adopt a modular structure by reusing and reassembling existing modules without building from scratch. They can embed one structure inside another in an intuitive way while preserving localism, and the language specification is simple, successfully balancing practicality and minimalism.
+
+Building on top of the excellent design of Go, the aim for Gno programming is to become the new gold standard for smart contract development, not just in our ecosystem but blockchain as a whole. Combining Go's large success, together with type safety and composability, Gno aims to kickstart a broader adoption of Web3 and its growth.

docs/explanation/gno-modules.md

@@ -0,0 +1,47 @@
+---
+id: gno-modules
+---
+
+# Gno Modules
+
+The packages and realms containing `gno.mod` file can be reffered as Gno modules. `gno.mod` file is introduced to enhance local testing and handle dependency management while testing Gno packages/realms locally. While it primarily serves local development and testing purposes, blockchain do not recognize or utilize this file directly.
+
+## What is the gno.mod file for?
+
+`gno.mod` file is a critical for local testing and development. Its primary purposes include:
+
+- **Local Dependency Management**: The gno.mod file allows you to manage local dependencies effectively when developing God Modules. This facilitates testing and iterative development.
+
+- **Module Sorting while Publishing**: Additionally, the gno.mod file is used to sort and automatically publish modules that are located within the `/examples` directory to the blockchain when the chain starts.
+
+- **Configuration and Metadata (Potential Future Use)**: While the gno.mod file is currently used for specifying dependencies, it's worth noting that in the future, it might also serve as a container for additional configuration and metadata related to Gno Modules. This could include information such as module descriptions, veriosn, authorship details, or licensing information. (See: https://github.com/gnolang/gno/issues/498)
+
+## Gno Modules and Subdirectories
+
+It's important to note that Gno Modules do not include subdirectories. Each directory within your project is treated as an individual Gno Module, and each should contain its own gno.mod file, even if it's located within an existing Gno Module directory.
+
+## Available gno Commands
+
+The gno command-line tool provides several commands to work with the gno.mod file and manage dependencies in Gno Modules:
+
+- `gno mod init`: Initializes a new `gno.mod` file. Allowing you to specify dependencies.
+
+- **gno mod download**: Downloads the dependencies specified in the gno.mod file. This command fetches the required dependencies from chain and ensures they are available for local testing and development.
+
+- **gno mod tidy**: This command helps maintain the cleanliness of the gno.mod file by removing any unused dependencies and automatically adds any dependencies that are required but not yet listed in the gno.mod file. It ensures that your gno.mod file remains up-to-date and free from unnecessary clutter, eliminating the need for manual maintenance.
+
+## Sample `gno.mod` file
+
+```
+module gno.land/p/demo/sample
+
+require (
+    gno.land/p/demo/avl v0.0.0-latest
+    gno.land/p/demo/testutils v0.0.0-latest
+)
+
+```
+
+- **`module gno.land/p/demo/sample`**: Specifies the package/realm import path.
+
+- **`require` Block**: Lists the required dependencies. Here using the latest available versions of "gno.land/p/demo/avl" and "gno.land/p/demo/testutils". These dependencies should be specified with the version "v0.0.0-latest" since as of now on-chain packages do not support versioning.

docs/explanation/gno-test.md

@@ -0,0 +1,82 @@
+---
+id: gno-test
+---
+
+# Gno Test
+
+There are two methods for testing a realm or package during the development phase:
+
+1. Calling the realm/package after deploying it on a local network (or testnet).
+2. Using the `test` option within the [`gno`](./gno-tooling/cli/gno.md) CLI.
+
+While the first method is recommended for its accuracy and similarity to the actual deployment environment, it is more efficient to initially utilize the second method for composing test cases and then proceed to the first method if no errors are detected.
+
+This section will teach you how to use the second method.
+
+Writing test cases in Gnolang is similar to that of Golang, with general rules as the following:
+
+* Test file naming conventions must be adhered to (ex: `xxx_test.gno`).
+* Test functions must start with `Test`.
+* The `t *testing.T` argument must be included in each test function.
+  * The `testing` package must be imported.
+* Tests must be run with the `gno test` command.
+
+Let's write a sample code and test it.
+
+```go
+// contract.gno
+
+package demo
+
+func Hello(name string) string {
+	return "Hello " + name + "!"
+}
+```
+
+This is a simple code that returns the string-typed argument in a specific format.
+
+Next, we'll write a test case that looks like the following:
+
+```go
+// contract_test.gno
+
+package demo
+
+import "testing"
+
+func Test(t *testing.T) {
+  {
+  	got := Hello("People")
+  	expected := "Hello People!"
+  	if got != expected {
+  		t.Fatalf("expected %q, got %q.", expected, got)
+  	}
+  }
+  {
+  	got := Hello("")
+  	expected := "Hello People!"
+  	if got != expected {
+  		t.Fatalf("expected %q, got %q.", expected, got)
+  	}
+  }
+}
+```
+
+Two conditions exist in the test case above.
+
+1. "Hello People!" should be returned when calling `Hello("People")`.
+2. "Hello People!" should be returned when calling `Hello("")`.
+
+Upon examination of our realm code and the associated test results, the initial condition exhibited the desired behavior; however, an error was identified in the second condition. Despite the expected outcome of "Hello" being returned, the test case incorrectly specified that the expected output should be "Hello People!" instead.
+
+Replacing the second test case with the following will successfully fix the issue and allow the test to pass.
+
+```go
+  {
+  	got := Hello("")
+  	expected := "Hello !"
+  	if expected != got {
+  		t.Fatalf("expected %q, got %q.", expected, got)
+  	}
+  }
+```

docs/explanation/gno-tooling/cli/common-params.md

@@ -0,0 +1,16 @@
+---
+id: gno-tooling-common-params
+---
+
+# Common Parameters
+
+Below is a list of common parameters.
+
+| Name                      | Description                          | Default                                  |
+| ------------------------- | ------------------------------------ | ---------------------------------------- |
+| `home`                    | The home directory.                  | `GNO_HOME` or the user's home directory. |
+| `remote`                  | The remote node URL.                 | `127.0.0.1:26657`                        |
+| `quiet`                   | For parsing output.                  | `false`                                  |
+| `insecure-password-stdin` | INSECURE! Takes password from stdin. | `false`                                  |
+
+

docs/explanation/gno-tooling/cli/gno.md

@@ -0,0 +1,66 @@
+---
+id: gno-tooling-gno
+---
+
+# gno
+
+`gno` is a handy tool for developing and prototyping Gno packages and realms. You may use `gno` to use the GnoVM without an actual blockchain to build or test realms in a local environment.
+
+## Run `gno` Commands
+
+The following command will run `gno`.
+
+```bash
+gno {SUB_COMMAND}
+```
+
+**Subcommands**
+
+| Name         | Description                                |
+| ------------ | ------------------------------------------ |
+| `build`      | Builds a gno package.                      |
+| `test`       | Tests a gno package.                       |
+| `precompile` | Precompiles a `.gno` file to a `.go` file. |
+| `repl`       | Starts a GnoVM REPL.                       |
+
+### `build`
+
+#### **Options**
+
+| Name      | Type    | Description                                    |
+| --------- | ------- | ---------------------------------------------- |
+| `verbose` | Boolean | Displays extended information.                 |
+| go-binary | String  | Go binary to use for building (default: `go`). |
+
+### `test`
+
+#### **Options**
+
+| Name         | Type          | Description                                                        |
+| ------------ | ------------- | ------------------------------------------------------------------ |
+| `verbose`    | Boolean       | Displays extended information.                                     |
+| `root-dir`   | String        | Clones location of github.com/gnolang/gno (gno tries to guess it). |
+| `run`        | String        | Test name filtering pattern.                                       |
+| `timeout`    | time.Duration | The maximum execution time in ns.                                  |
+| `precompile` | Boolean       | Precompiles a `.gno` file to a `.go` file before testing.          |
+
+### `precompile`
+
+#### **Options**
+
+| Name        | Type    | Description                                                     |
+| ----------- | ------- | --------------------------------------------------------------- |
+| `verbose`   | Boolean | Displays extended information.                                  |
+| `skip-fmt`  | Boolean | Skips the syntax checking of generated `.go` files.             |
+| `go-binary` | String  | The go binary to use for building (default: `go`).              |
+| `go-binary` | String  | The gofmt binary to use for syntax checking (default: `gofmt`). |
+| `output`    | String  | The output directory (default: `.`).                            |
+
+### `repl`
+
+#### **Options**
+
+| Name       | Type    | Description                                                        |
+| ---------- | ------- | ------------------------------------------------------------------ |
+| `verbose`  | Boolean | Displays extended information.                                     |
+| `root-dir` | String  | Clones location of github.com/gnolang/gno (gno tries to guess it). |

docs/explanation/gno-tooling/cli/gnofaucet.md

@@ -0,0 +1,53 @@
+---
+id: gno-tooling-gnofaucet
+---
+
+# gnofaucet
+
+`gnofaucet` is a server for distributing GNOT, the gas currency of Gnoland, to specific addresses in a local chain. Interact with the `gnofaucet` from an address with an empty balance in your locally built testnet to fuel it with GNOT to pay for transactions.
+
+## Run `gnofaucet` Commands
+
+Enable the faucet using the following command.
+
+```bash
+gnofaucet serve
+```
+
+#### **Options**
+
+| Name                      | Type    | Description                                                                          |
+| ------------------------- | ------- | ------------------------------------------------------------------------------------ |
+| `chain-id`                | String  | The id of the chain (required).                                                      |
+| `gas-wanted`              | Int64   | The maximum amount of gas to use for the transaction (default: `50000`)              |
+| `gas-fee`                 | String  | The gas fee to pay for the transaction.                                              |
+| `memo`                    | String  | Any descriptive text (default: `""`)                                                 |
+| `test-to`                 | String  | Test address (optional) 부연설명 필요                                                |
+| `send`                    | String  | Coins to send (default: `"1000000ugnot"`).                                           |
+| `captcha-secret`          | String  | The secret key for the recaptcha. If empty, the captcha is disabled (default: `""`). |
+| `is-behind-proxy`         | Boolean | Uses X-Forwarded-For IP for throttling (default: `false`).                           |
+| `insecure-password-stdin` | Boolean | INSECURE! Takes password from stdin (default: `false`).                              |
+
+## Example
+
+### Step 1. Create an account named `test1` with the test seed phrase below.
+
+```bash
+gnokey add test1 --recover
+```
+
+> **Test Seed Phrase:** source bonus chronic canvas draft south burst lottery vacant surface solve popular case indicate oppose farm nothing bullet exhibit title speed wink action roast
+
+### **Step 2. Run `gnofaucet`**
+
+```bash
+gnofaucet serve test1 --chain-id dev --send 500000000ugnot
+```
+
+### **Step 3. Receive GNOTs from the faucet**
+
+```bash
+curl --location --request POST 'http://localhost:5050' \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--data-urlencode 'toaddr={address to receive}'
+```