docs: standard library, banker, coins, address

docs/concepts/packages.md

@@ -4,9 +4,11 @@ id: packages
 
 # Packages
 
-Packages encompass functionalities that are more closely aligned with the characteristics and capabilities of realms, as opposed to standard libraries.
+Packages aim to encompass functionalities that are more closely aligned with the characteristics and capabilities of realms, as opposed to standard libraries. As opposed to realms, they are stateless.
 
-The full list of available packages can be found in [the demo package](https://github.com/gnolang/gno/tree/master/examples/gno.land/p/demo). Below are some of the most commonly used packages.
+Typically deployed under `../p/demo`, packages 
+
+The full list of pre-deployed available packages can be found under the [demo package](https://github.com/gnolang/gno/tree/master/examples/gno.land/p/demo). Below are some of the most commonly used packages.
 
 ## `avl`
 

docs/concepts/standard-library/banker.md

@@ -0,0 +1,27 @@
+---
+id: banker
+---
+
+# Banker
+
+The Banker's main purpose is to handle balance changes of native coins (link native coin) within Gno chains. This includes issuance, transfers, and burning of [Coins](coins.md). 
+
+The Banker module can be cast into 4 subtypes of bankers that expose different functionalities and safety features within your packages and realms.
+
+[//]: # (The banker module is injected into the GnoVM runtime at execution. )
+
+### Banker Types
+
+1. `BankerTypeReadOnly` - read-only access to coin balances
+2. `BankerTypeOrigSend` - full access to coins sent with the transaction that calls the banker
+3. `BankerTypeRealmSend` - full access to coins that the realm itself owns, including the ones sent with the transaciton
+4. `BankerTypeRealmIssue` - able to issue new coins
+
+You can access the Banker from within the `std` namespace by calling `std.GetBanker(<BankerType>)` in your package/realm.
+
+The Banker API can be found in [Banker Reference].
+
+
+
+
+

docs/concepts/standard-library/coins.md

@@ -0,0 +1,30 @@
+---
+id: coin
+---
+
+# Coin
+
+A Coin is a native Gno object that has a denomination and an amount. Coins can be issued by the [Banker](banker.md). 
+
+A coin is defined by the following:
+
+```go
+type Coin struct {
+ Denom string `json:"denom"`
+ Amount int64 `json:"amount"`
+}
+```
+
+Multiple coins can be bundled together into a `Coins` type:
+
+```go
+type Coins []Coin
+```
+
+The `Coins` slice can be included in a transaction made by a user addresses or a realm. 
+They are then available for access by specific types of Bankers, which can manipulate them depending on their access rights. 
+
+
+
+
+

docs/concepts/standard-library/native-bindings.md

@@ -0,0 +1,64 @@
+---
+id: native-bindings
+---
+
+## Native bindings
+
+Gno has support for "natively-defined functions" exclusively within the standard
+libraries. These are functions which are _declared_ in Gno code, but only _defined_
+in Go. There are generally three reasons why a function should be natively
+defined:
+
+1. It relies on inspecting the Gno Virtual Machine itself, i.e. `std.AssertOriginCall`
+or `std.CurrentRealmPath`.
+2. It relies on `unsafe`, or other features which are not planned to be
+ available in the GnoVM, i.e. `math.Float64frombits`.
+3. Its native Go performance significantly outperforms the Gno counterpart by
+ several orders of magnitude, and it is used in crucial code or hot paths in
+ many programs, i.e. `sha256.Sum256`.
+
+Native bindings are made to be a special feature which can be
+help overcome pure Gno limitations, but it is not a substitute for writing
+standard libraries in Gno.
+
+There are three components to a natively bound function in Gno:
+
+1. The Gno function declaration, which must be a top-level function with no body
+ (and no brackets), i.e. `crypto/sha256/sha256.gno`.
+2. The Go function definition, which must be a top-level function with the same
+ name and signature, i.e. `crypto/sha256/sha256.go`.
+3. When the two above are present and valid, the native binding can be created
+ by executing the code generator: either by executing `go generate` from the
+ `stdlibs` directory, or run `make generate` from the `gnovm` directory.\
+ This generates the `native.go` file available in the `stdlibs` directory,
+ which provides the binding itself to then be used by the GnoVM.
+
+The code generator in question is available in the `misc/genstd` directory.
+There are some quirks and features that must be kept in mind when writing native
+bindings, which are the following:
+
+- Unexported functions (i.e. `func sum256(b []byte)`) must have their
+ Go counterpart prefixed with `X_` in order to make the functions exported (i.e.
+ `func X_sum256(b []byte)`).
+- The Go function declaration may specify as the first argument
+ `m *gno.Machine`, where `gno` is an import for
+ `github.com/gnolang/gno/gnovm/pkg/gnolang`. This gives the function access to
+ the Virtual Machine state, and is used by functions like `std.AssertOriginCall()`.
+- The Go function may change the type of any parameter or result to
+ `gno.TypedValue`, where `gno` is an import for the above import path. This
+ means that the `native.go` generated code will not attempt to automatically
+ convert the Gno value into the Go value, and can be useful for unsupported
+ conversions like interface values.
+- A small set of named types are "linked" between their Gno version and Go
+ counterpart. For instance, `std.Address` in Gno is
+ `(".../tm2/pkg/crypto").Bech32Address` in Go. A list of these can be found in
+ `misc/genstd/mapping.go`.
+- Not all type literals are currently supported when converting from their Gno
+ version to their Go counterpart, i.e. `struct` and `map` literals. If you intend to use these,
+ modify the code generator to support them.
+- The code generator does not inspect any imported packages from the Go native code
+ to determine the default package identifier (i.e. the `package` clause).
+ For example, if a package is in `foo/bar`, but declares `package xyz`, when importing
+ foo/bar the generator will assume the name to be `bar` instead of `xyz`.
+ You can add an identifier to the import to fix this and use the identifier
+ you want/need, such as `import gno "github.com/gnolang/gno/gnovm/pkg/gnolang"`.

docs/concepts/standard-library/overview.md

@@ -0,0 +1,91 @@
+---
+id: overview
+---
+
+# Overview
+
+The Gno Standard Library
+- Standard libraries as we know them in Golang, i.e. `"encoding/binary`, `strings` etc. 
+- The `std` package, which contains blockchain-specific types and functionalities, like the [Banker](./banker.md), [coins](./coins.md), addresses, etc.
+
+## Accessing Gno.land documentation
+
+Apart from the official documentation you are currently reading, you can also access documentation for the standard
+libraries in several other different ways. You can obtain a list of all the available standard libraries with the following commands:
+
+```console
+$ cd gnovm/stdlibs # go to correct directory
+
+$ find -type d
+./testing
+./math
+./crypto
+./crypto/chacha20
+./crypto/chacha20/chacha
+./crypto/chacha20/rand
+./crypto/sha256
+./crypto/cipher
+...
+```
+
+All the packages have automatically generated documentation through the use of
+`gno doc` command, which has similar functionality and features to `go doc`:
+
+```console
+$ gno doc encoding/binary
+package binary // import "encoding/binary"
+
+Package binary implements simple translation between numbers and byte sequences
+and encoding and decoding of varints.
+
+[...]
+
+var BigEndian bigEndian
+var LittleEndian littleEndian
+type AppendByteOrder interface{ ... }
+type ByteOrder interface{ ... }
+$ gno doc -u -src encoding/binary littleEndian.AppendUint16
+package binary // import "encoding/binary"
+
+func (littleEndian) AppendUint16(b []byte, v uint16) []byte {
+ return append(b,
+ byte(v),
+ byte(v>>8),
+ )
+}
+```
+
+`gno doc` will work automatically when used within the Gno repository or any
+repository which has a `go.mod` dependency on `github.com/gnolang/gno`, which
+can be a simple way to set up your Gno repositories to automatically support
+`gno` commands (aside from `doc`, also `test`, `run`, etc.).
+
+Another alternative is setting your enviornment variable `GNOROOT` to point to
+where you cloned the Gno repository. You can set this in your `~/.profile` file
+to be automatically set up in your console:
+
+```sh
+export GNOROOT=$HOME/gno
+```
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

docs/how-to-guides/testing-gno.md

@@ -175,7 +175,7 @@ Luckily, the Gno standard library provides ample support for functionality such
 time, such as the request caller address, or the calling package address.
 
 You can learn more about these methods, that are importable using the `std` import declaration,
-in the [Standard Library](../reference/standard-library.md) reference section.
+in the [Standard Library](../concepts/standard-library/overview.md) reference section.
 
 ## Conclusion
 

docs/reference/standard-library.md

@@ -16,67 +16,8 @@ programming language rather than with the Gno.land chain.
 
 Many standard libaries are near-identical copies of the equivalent Go standard
 libraries; in fact, you can check the current status of implementation of each
-Go standard libarary on [Go\<\>Gno compatibility](go-gno-compatibility.md).
-
-## Gathering documentation
-
-At the time being, there is no "list" of the available standard libraries
-available from Gno tooling or documentation, but you can obtain a list of all
-the available packages with the following commands:
-
-```console
-$ cd gnovm/stdlibs # go to correct directory
-$ find -type d
-./testing
-./math
-./crypto
-./crypto/chacha20
-./crypto/chacha20/chacha
-./crypto/chacha20/rand
-./crypto/sha256
-./crypto/cipher
-...
-```
-
-All of the packages have automatic, generated documentation through the use of
-`gno doc`, which has similar functionality and features to `go doc`:
-
-```console
-$ gno doc encoding/binary
-package binary // import "encoding/binary"
-
-Package binary implements simple translation between numbers and byte sequences
-and encoding and decoding of varints.
-
-[...]
-
-var BigEndian bigEndian
-var LittleEndian littleEndian
-type AppendByteOrder interface{ ... }
-type ByteOrder interface{ ... }
-$ gno doc -u -src encoding/binary littleEndian.AppendUint16
-package binary // import "encoding/binary"
-
-func (littleEndian) AppendUint16(b []byte, v uint16) []byte {
- return append(b,
- byte(v),
- byte(v>>8),
- )
-}
-```
-
-`gno doc` will work automatically when used within the Gno repository or any
-repository which has a `go.mod` dependency on `github.com/gnolang/gno`, which
-can be a simple way to set up your Gno repositories to automatically support
-`gno` commands (aside from `doc`, also `test`, `run`, etc.).
-
-Another alternative is setting your enviornment variable `GNOROOT` to point to
-where you cloned the Gno repository. You can set this in your `~/.profile` file
-to be automatically set up in your console:
-
-```sh
-export GNOROOT=$HOME/gno
-```
+Go standard libarary on [Go<\>Gno compatibility](go-gno-compatibility.md).
+
 
 ## Test standard libraries
 
@@ -126,69 +67,4 @@ Some things to keep in mind:
 If you intend to create a PR to add a new standard library, remember to update
 [Go\<\>Gno compatibility](go-gno-compatibility.md) accordingly.
 
-## Native bindings
-
-Gno has support for "natively-defined functions" exclusively within the standard
-libaries. These are functions which are _declared_ in Gno code, but only _defined_
-in Go. There are generally three reasons why a function should be natively
-defined:
-
-1. It relies on inspecting the Gno Virtual Machine itself.\
- For example: `std.AssertOriginCall`, `std.CurrentRealmPath`.
-2. It relies on `unsafe`, or other features which are not planned to be
- available in the GnoVM.\
- For example: `math.Float64frombits`.
-3. Its native Go performance significantly outperforms the Gno counterpart by
- several orders of magnitude, and it is used in crucial code or hot paths in
- many programs.\
- For example: `sha256.Sum256`.
-
-The takeaway here is that native bindings are a special feature which can be
-useful to overcome pure Gno limitations, but it is not a substitute for writing
-standard libaries in Gno.
-
-There are three components to a natively bound function in Gno:
-
-1. The Gno function declaration, which must be a top-level function with no body
- (and no brackets).\
- For example: `crypto/sha256/sha256.gno`.
-2. The Go function definition, which must be a top-level function with the same
- name and signature.\
- For example: `crypto/sha256/sha256.go`.
-3. When the two above are present and valid, the native binding can be created
- by executing the code generator: either execute `go generate` from the
- `stdlibs` directory, or run `make generate` from the `gnovm` directory.\
- This generates the `native.go` file available in the `stdlibs` directory,
- which provides the binding itself to then be used by the GnoVM.
-
-The code generator in question is available in the `misc/genstd` directory.
-There are some quirks and features that must be kept in mind when writing native
-bindings, which are the following:
-
-- Unexported functions (for instance, `func sum256(b []byte)`) must have their
- Go counterpart prefixed with `X_` in order to make the functions exported (ie.
- `func X_sum256(b []byte)`).
-- The Go function declaration may specify as the first argument
- `m *gno.Machine`, where `gno` is an import for
- `github.com/gnolang/gno/gnovm/pkg/gnolang`. This gives the function access to
- the Virtual Machine state, and is used by functions like `std.AssertOriginCall()`.
-- The Go function may change the type of any parameter or result to
- `gno.TypedValue` (where `gno` is an import for the above import path). This
- means that the `native.go` generated code will not attempt to automatically
- convert the Gno value into the Go value, and can be useful for unsupported
- conversions like interface values.
-- A small set of named types are "linked" between their Gno version and Go
- counterpart. For instance, `std.Address` in Gno is
- `(".../tm2/pkg/crypto").Bech32Address` in Go. A list of these can be found in
- `misc/genstd/mapping.go`.
-- Not all type literals are currently supported when converting from their Gno
- version to their Go counterpart. Notable omissions at the time of writing
- include struct and map literals. If you intend to use these, modify the code
- generator to support them.
-- The code generator does not inspect any imported packages from the Go native code
- to determine the default package identifier (ie. the `package` clause).
- Ie. if a package is in `foo/bar`, but declares `package xyz`, when importing
- foo/bar the generator will assume the name to be `bar` instead of `xyz`.
- You can add an identifier to the import to fix this and use the identifier
- you want/need, ie.: `import gno "github.com/gnolang/gno/gnovm/pkg/gnolang"`.