Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add first documentation archetype. #957

Closed
wants to merge 2 commits into from
Closed
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions docs/daos.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
state: design # Nothing implemented yet, figuring out the best way to do it.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What kinds of states do we have in total?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

right now, 3:

  • improvements-needed: The final PoC is working well, but it must evolve performance-wise.
  • design: Nothing implemented yet, figuring out the best way to do it.
  • done: it is done (nothing yet)

---

# DAOs
Decentralized Autonomous Organizations are represented as a group of [Realm](./realm.md)s or/and [package](.)s that can manage decisions using the blockchain. We have several DAOs that will be in charge of:
Copy link
Member

@thehowl thehowl Jul 7, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mmh, it's actually people, no? I see it as decision-making regulated through code


- [OP Values prize DAO](.): It will define the prize per VM Op.
- [Evaluation DAO](evaluation-dao.md): It will be in charge of making [Proof of Contribution](.) works.
10 changes: 10 additions & 0 deletions docs/evaluation-dao.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
---
state: design # Nothing implemented yet, figuring out the best way to do it.
---

# Evaluation DAO

It is a smart contract framework for reviewing, measuring, and accepting contributions. It is not the consensus mechanism but rather a platform.

It scales itself -> managed by its members; serving as an entry point to become a new member.
V1 is currently being developed as a [GoR](.) (Game of Realms) task.
3 changes: 3 additions & 0 deletions docs/gno.land.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# gno.land

gno.land is a reference to all applications included in the ecosystem, from [Tendermint V2](./new-tendermint.md) to [Gnovm](./gnovm.md), also including [Gnoweb](./gnoweb.md) and others.
12 changes: 12 additions & 0 deletions docs/gnode.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
state: design # Nothing implemented yet, figuring out the best way to do it.
---

# Gnodes

Gnodes are interconnected [DAOs](./daos.md) for scaling and specialized communities. They enable secure collaboration and seamless integration, facilitating transparent ecosystem management at scale.

Layers and overlays for different perspectives:
- first layer: entities, people, and connections to projects and teams.
ajnavarro marked this conversation as resolved.
Show resolved Hide resolved
- second layer: relationships between entities, burn rate, payments (the "basic income" layer)
- third layer: conflicts of interest, ownership stakes (privacy-preserving)
7 changes: 7 additions & 0 deletions docs/gnovm.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
state: improvements-needed # The final PoC is working well, but it must evolve performance-wise.
---

# Gnovm

Gnovm is in charge to run [Gno](.) code. It interprets directly the source code and parses it to an AST. After that, it emulates CPU instructions to execute the AST instead of executing it directly. It is able to store the state of a [Realm](./realm.md) and retrieve it on the next execution.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it emulates CPU instructions to execute the AST instead of executing it directly

unclear; I would suggest something like "interprets the AST to execute its code, similarly to Python, in contrast to executing machine code directly, like Go with the official compiler".

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I propose(combines discussion above): "Gnovm is in charge to run Gno code. Firstly, Gno source code is parsed into an Abstract Syntax Tree (AST). Then, Gnovm interprets the AST to execute the code. This process bears similarity to Python's execution model, which contrasts with that of Go's official compiler that directly executes machine code..."

Copy link
Contributor Author

@ajnavarro ajnavarro Jul 10, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest something like "interprets the AST to execute its code, similarly to Python, in contrast to executing machine code directly, like Go with the official compiler".

I would prefer to explain things as they are instead of using other languages as examples. Some people might not know how Python interpreter works.

edit: where are we talking in your rewordings about OP codes? we are not just executing the AST but generating a list of OP codes that will be executed.

9 changes: 9 additions & 0 deletions docs/gnoweb.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
state: improvements-needed # The final PoC is working well, but it must evolve performance-wise.
---

# Gnoweb

gnoweb is an application that can call a special method on a [realm](./realm.md) that returns markdown as the output. This can be used to create any kind of web interface, like social networks, blog systems, forums, or standard status pages.

The method that it calls is `Render(string)`string` where the input string is a path, and the output string is markdown.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The method that it calls is `Render(string)`string` where the input string is a path, and the output string is markdown.
The method that it calls is `Render(string) string` where the input is a path (to discriminate different requests, and potentially handle them through a router), and the return value is markdown to be rendered.

I would also add something like:

It has read-only access also to the [Realm State](./realm-state.md), so it can serve as a useful bridge between web2 and content on web3.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just a note that the output of Render does not have to be markdown specifically

12 changes: 12 additions & 0 deletions docs/ibc-protocol.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
state: improvements-needed # The final PoC is working well, but it must evolve performance-wise.
ajnavarro marked this conversation as resolved.
Show resolved Hide resolved
---

# IBC Protocol

The Inter-Blockchain Communication Protocol (IBC) allows independent blockchains to directly communicate and trade assets.

- The Inter‐Blockchain Communication Protocol (IBC), an open‐source protocol for relaying messages between independently distributed ledgers, was created to connect independent blockchains.
- IBC allows heterogeneous chains to trustlessly communicate with each other and exchange value, particularly tokens, which makes them interoperable.
- A key feature of IBC is that the connected blockchains do not need to communicate with each other directly. Instead, they can send packets of information via dedicated channels using smart contracts to connect to the chains.
- The Tendermint‐based decentralized exchange [Osmosis](https://www.coinbase.com/cloud/discover/protocol-guides/guide-to-osmosis) allows token holders to directly benefit from what IBC offers by enabling seamless swaps of tokens from different chains.
7 changes: 7 additions & 0 deletions docs/new-tendermint.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
state: improvements-needed # The final PoC is working well, but it must evolve performance-wise.
---

# New Tendermint
ajnavarro marked this conversation as resolved.
Show resolved Hide resolved

Tendermint is a consensus algorithm based on the Byzantine-Fault Tolerance algorithm. In gno.land, it is in charge of replicating the Gno VM machine state among all the nodes on the network.
ajnavarro marked this conversation as resolved.
Show resolved Hide resolved
11 changes: 11 additions & 0 deletions docs/realm-state.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
state: improvements-needed # The final PoC is working well, but it must evolve performance-wise.
---

# Realm State

State stores the state of a Realm. It stores all the Realm public variables as a Merkle tree.

## Format

TODO
9 changes: 9 additions & 0 deletions docs/realm.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---
state: improvements-needed # The final PoC is working well, but it must evolve performance-wise.
---

# Realm

A realm is the equivalent of a smart contract. It is a program that cannot be powered off.

All public methods of a Realm can be accessed by anyone, and all the global variables will be stored between executions as the [State](./realm-state.md)