From 4f5f0c4526c8661eea3912ea53f1cc6100bf80b0 Mon Sep 17 00:00:00 2001 From: lunfardo314 Date: Thu, 6 Feb 2025 20:42:11 +0200 Subject: [PATCH] testnet docs --- README.md | 7 ++-- docs/inflate.md | 47 ------------------------- docs/proxi.md | 11 ++---- docs/testnet.md | 81 +++++++++++++++++++++++++++++++++++++++++++ proxi/main.go | 2 ++ proxi/version/init.go | 25 +++++++++++++ 6 files changed, 116 insertions(+), 57 deletions(-) delete mode 100644 docs/inflate.md create mode 100644 docs/testnet.md create mode 100644 proxi/version/init.go diff --git a/README.md b/README.md index 527f1458..8214b3e0 100644 --- 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).
It is similar to *proof-of stake* (PoS), especially because of its energy-efficiency and throughput.
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 deleted file mode 100644 index adfb0430..00000000 --- a/docs/inflate.md +++ /dev/null @@ -1,47 +0,0 @@ -## Inflation. Creating tokens out of thin air with `proxi` - -Proxima ledger has inflation. In theory, every token holder can inflate their holdings, i.e. create tokens out of thin air. - -In practice, however, there certain parameters who, how and when can create positive inflation. -The constraint is: new tokens can be created only on outputs called **chain outputs**. - -For those who know IOTA's UTXO ledger, Proxima's _chain outputs_ are similar to IOTA's _alias outputs_. - -Chain output is an output (UTXO) with special script on it, called _chain constraint_. -It has unique ID called _chain ID_. The _chain ID_ is assigned by the ledger upon creation of the _chain origin_. -Chain outputs are consumed and produced in chains of transactions, each with chain output with the same _chain ID_. - -Chain output, like any other output, contain certain amount of tokens on it. It s called _on-chain balance_. - -New tokens (inflation) are created on the _successor_ chain output and inflation amount is proportional to the _on-chain balance_ -of the _predecessor_ and to ledger time (in ticks) between predecessor and successor. Time is money. - -To inflate your holdings, you create a chain using command `proxi node mkchain, `. - -The command creates chain origin with `` tokens on it. The newly assigned _chain ID_ is displayed. -One can always display all chains controlled by the wallet's private key with command `proxi node chains`. - -To destroy the chain and return all tokens to the usual address command `proxi node delchain ` can be used. - -Note, that each of these commands will require certain tag-along fee paid to the sequencer of choice. - -Proxima ledger (testnet version) has maximum total annual inflation capped by fixed amount. -In the first year it is approximately 10% of the initial supply. Initial supply is equal to `1.000.000.000.000.000` tokens, -so maximum annual inflation is approximately `100.000.000.000.000`. - -Given these numbers, it means that on each chain transaction maximum possible inflation is rather small. - -For example `1.000.000.000` (1 billion) tokens will generate inflation ~350 tokens per each 10 slots (1.5 minutes), or about -35 tokens per slot. - -Smaller amounts on chain will generate 0 tokens of inflation. It puts natural limits of how big/small -token holdings are meaningful for the inflation. - -Use command `proxi node inflate ` to start inflating your on-chain balance. - -The command will start issuing chain transactions every 10 slots and create new tokens on it. -Flag `-s ` allows to change default number of slots (10) to any number from 2 and uo to 12. -Note, that each of these transactions will cost a fee, so it does not make sense to issue them too often. -Besides, 12 is maximum number of slots which allows positive inflation: it is so-called _inflation opportunity window_. - -So, token holdings at least `100.000.000` and command `proxi node inflate ` is close to optimal.x \ No newline at end of file diff --git a/docs/proxi.md b/docs/proxi.md index 15d62ad4..ff6a5581 100644 --- 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: ``` -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://:` +`api.endpoint` must contain URL for the node's API in the form of `http://:`. **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 -t ""` 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 new file mode 100644 index 00000000..35d9ca77 --- /dev/null +++ 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)`), 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 index 59aa125b..7f69b6b6 100644 --- 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 new file mode 100644 index 00000000..37356ad6 --- /dev/null +++ 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) +}