testnet docs

lunfardo314 · Feb 6, 2025 · 4f5f0c4 · 4f5f0c4
1 parent cf64639
commit 4f5f0c4
Show file tree

Hide file tree

Showing 6 changed files with 116 additions and 57 deletions.
diff --git a/README.md b/README.md
@@ -1,14 +1,16 @@
 *Warning! This repository contains an ongoing development. Currently, it is in an alpha version. It definitely contains bugs.
 The code should not be used in production!*
 
-*For up-to-date information see `develop` branch*
-
 # Proxima: a DAG-based cooperative distributed ledger
 Proxima is as decentralized and permissionless as Bitcoin (*proof-of-work*, PoW). 
 <br>It is similar to *proof-of stake* (PoS), especially because of its energy-efficiency and throughput.
 <br>Yet it is neither PoW, nor a PoS system. It is based on **cooperative consensus**. See [whitepaper](https://arxiv.org/abs/2411.16456) and 
 [simplified presentation of Proxima concepts](https://hackmd.io/@Evaldas/Sy4Gka1DC).
 
+## Testnet 
+
+Please read instructions [how to join open testnet](docs/testnet.md).
+
 ## Introduction
 Proxima presents a novel architecture for a distributed ledger, commonly referred to as a "blockchain". 
 The ledger of Proxima is organized in the form of directed acyclic graph (DAG) with UTXO transactions as vertices, 
@@ -78,6 +80,7 @@ much simpler than most PoS systems, which are usually complex in their consensus
   * [Running node with sequencer](docs/run_sequencer.md)
   * [Running small testnet in Docker](tests/docker/docker-network.md)
   * [Delegation in `proxi`](docs/delegate.md)
+  * [How to join testnet?](docs/testnet.md)
 * Introductory videos:
   * [1. Introduction. Principles of Nakamoto consensus](https://youtu.be/qDnjnrOJK_g)
   * [2. UTXO tangle. Ledger coverage](https://youtu.be/CT0_FlW-ObM)

diff --git a/docs/inflate.md b/docs/inflate.md
diff --git a/docs/proxi.md b/docs/proxi.md
@@ -37,11 +37,6 @@ api:
 tag_along:
   sequencer_id: 6393b6781206a652070e78d1391bc467e9d9704e9aa59ec7f7131f329d662dcc
   fee: 500
-finality:
-  inclusion_threshold:
-    numerator: 2
-    denominator: 3
-  weak: false
 spammer:
   bundle_size: 5
   output_amount: 1000
@@ -52,7 +47,7 @@ spammer:
   target: <target address in EasyFL format>
 ```
 
-Usually some adjustments are needed to complete the profile. 
+**Usually some adjustments are needed to complete the profile**. 
 
 `wallet.private_key` contains hex encoded raw data of the ED25519 private key. The file must be kept secret 
 because of this private key. 
@@ -63,7 +58,7 @@ _EasyFL_ script fro the ED25519 lock.
 `sequencer_id` is an optional field. It is irrelevant if you do not run sequencer. It contains `sequencer ID` of the sequencer controlled by this wallet. 
 It is necessary in order to access sequencer controlled by this private key with the `proxi node seq withdraw ..` command. 
 
-`api.endpoint` must contain URL for the node's API in the form of `http://<ip>:<port>`
+`api.endpoint` must contain URL for the node's API in the form of `http://<ip>:<port>`. **It must be set to the address of some public access point**
 
 `tag_along.sequencer_id` is a mandatory field for any commands which create transactions, such as `proxi node transfer`.
 It must contain sequencer which is used as tag-along sequencer. Each issued transaction will contain so-called _tag-along output_.
@@ -120,7 +115,7 @@ by all the current healthy ledger states, i.e. it is the **consensus ledger stat
 * `proxi node balance` displays token balance on the usual (ED25519) address and on chains, controlled by the wallet's account in the LRB branch.  
    Token balance is sum of tokens contained in non-chain outputs plus sum of balances contained in chain outputs. 
 
-* `proxi node chains` displays all chain outputs controlled by the account on LRB state
+* `proxi node mychains` displays all chain outputs controlled by the account on the LRB state
 
 * `proxi node transfer <amount> -t "<target address>"` sends tokens from the wallet's account to the target address.
   For example command `proxi node transfer 1000 -t "a(0x370563b1f08fcc06fa250c59034acfd4ab5a29b60640f751d644e9c3b84004d0)"`

diff --git a/docs/testnet.md b/docs/testnet.md
@@ -0,0 +1,81 @@
+## Participating in the open testnet
+
+Proxima testnet is an experimental network, intended for testing node software and various aspects of the Proxima concept.
+
+We have been running several of them, each with at least 9 nodes and 5 sequencers among them. The testnets are
+
+Starting from version `v0.1.2` it is an open testnet. It means, everybody can join the network with the access node,
+everybody with enough tokens can run a sequencer and earn inflation.
+
+Starting from version `v0.1.3-testnet` network has faucet.
+
+Starting from version `v0.1.4-testnet`, the node has _delegation_ function implemented. It allows any token holder participate
+in the consensus and earn inflation by delegating their holding to a sequencer of choice. (note, that minimum token amount
+limits are applied). So, the network is more or less functionally complete, in a sense that node provides all core functions
+needed to demonstrate full decentralization, as intended.
+
+### Other docs
+Please read at least basic docs on [proxi](proxi.md), [delegation](delegate.md) and other available materials. 
+At this stage Proxima lacks proper documentation.
+
+### Public access points
+These are public API endpoints to access from `proxi` or for other purposes:
+
+* http://113.30.191.219:8001
+* http://63.250.56.190:8001
+* http://83.229.84.197:8001
+* http://5.180.181.103:8001
+
+The faucet is available on `113.30.191.219:9500`. You need the following section in your `proxi.yaml`:
+
+```yaml
+faucet:
+    port: 9500
+    addr: 113.30.191.219
+```
+
+### How to get tokens?
+Use command `proxi node getfunds` to get tokens to your wallet as defined by the `proxi.yaml` in you current directory.
+You can do it once per day. Faucet will send generous `1.000.000.000.000` tokens to your account. 
+
+Check you balance with command `proxi node balance`. If everything is ok, the requested tokens will come after 20-30 seconds. 
+
+This amount is ~0.1% of the total supply. It is enough to run sequencer and for delegation.
+
+### What you can do with your tokens?
+
+#### Transfer tokens between accounts
+
+To send tokens between accounts you use command `proxi node transfer`. See [proxi docs](proxi.md). 
+Note, that for this `proxi.yaml` must be configured properly. In particular, _tag-along sequencer_ and _tag-along fees_ must be
+configured properly. You can list all sequencers with command `proxi node allchains -q` and choose one of them as tag-along. 
+
+#### Earn inflation by delegation
+Please read [delegation](delegate.md). It is **strongly encouraged** to delegate all but some minimum amount (say `1.000.000`) of your tokens, 
+immediately you receive them with `proxi node getfunds`. 
+
+All sequencers with delegation information can be listed with `proxi node allchains -d -q`. It easy to choose one of them for delegation
+and tag-along.
+
+Your delegated tokens will contribute to the security of the network and, in exchange, will earn you inflation around **10% annually**. 
+If your tokens will remain passive in your normal account (which has address in the form `a(0x<hex>)`), you will not receive any inflation. 
+
+#### Earn inflation by running sequencer
+Tu run a sequencer you need two things:
+* to run an _access node_. See [Running access node](run_access.md) for detailed instructions. Note, that it is pretty easy to run access node
+and this does not require to own any tokens, but does not contribute to the security of the network.
+* configure and run a **sequencer** on that access node (then we call it _sequencer node_). See [Running node with the sequencer](run_sequencer.md). To run a sequencer you will need tokens.  
+Sequencers are programs which generate inflation and therefore contribute to the security of the network on behalf of the token holder. 
+Sequencers more than delegated tokens because they participate in the lottery for the *branch inflation bonus*. In addition to that, 
+sequencers collect tag along fees and delegation margin.
+
+### Disclaimer
+
+We will do our best to help you on the Proxima Discord channel `#testnet`. Please node, however, our resources are very limited. 
+We count on growing community which can help each other.
+
+Please also note that:
+
+* tokens are fake. They have 0 value and are only for testing.
+* the Proxima software at this stage is experimental and definitely contains bugs. Do not use it in production! 
+
diff --git a/proxi/main.go b/proxi/main.go
@@ -10,6 +10,7 @@ import (
 	"github.com/lunfardo314/proxima/proxi/init_cmd"
 	"github.com/lunfardo314/proxima/proxi/node_cmd"
 	"github.com/lunfardo314/proxima/proxi/snapshot_cmd"
+	"github.com/lunfardo314/proxima/proxi/version"
 	"github.com/spf13/cobra"
 	"github.com/spf13/viper"
 )
@@ -49,6 +50,7 @@ and withdraw funds from the sequencer chain
 		node_cmd.Init(),
 		gen_cmd.Init(),
 		snapshot_cmd.Init(),
+		version.CmdVersion(),
 	)
 	rootCmd.InitDefaultHelpCmd()
 	if err = rootCmd.Execute(); err != nil {

diff --git a/proxi/version/init.go b/proxi/version/init.go
@@ -0,0 +1,25 @@
+package version
+
+import (
+	"github.com/lunfardo314/proxima/global"
+	"github.com/lunfardo314/proxima/proxi/glb"
+	"github.com/spf13/cobra"
+)
+
+func CmdVersion() *cobra.Command {
+	verCmd := &cobra.Command{
+		Use:     "version",
+		Aliases: []string{"ver"},
+		Args:    cobra.NoArgs,
+		Short:   "displays version info of proxi",
+		Run:     runVersionCmd,
+	}
+	verCmd.InitDefaultHelpCmd()
+	return verCmd
+}
+
+func runVersionCmd(_ *cobra.Command, _ []string) {
+	glb.Infof("    Version:      %s", global.Version)
+	glb.Infof("    Commit time:  %s", global.CommitTime)
+	glb.Infof("    Commit hash:  %s", global.CommitHash)
+}