balsoft/ligo
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Add scripts/README.alphanet.

Browse Source
This commit is contained in:
Grégoire Henry 2017-08-10 16:08:58 +00:00 committed by Benjamin Canou
parent 4c31d084e1
commit af16d9d62c
5 changed files with 336 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
.gitlab-ci.yml
View File

@ -159,17 +159,7 @@ publish:github:
- if [ "${CI_PROJECT_PATH}" = "tezos/tezos" ] ; then
./scripts/apply_patch.sh "${CI_BUILD_REF_NAME}" ;
fi
- git filter-branch --prune-empty --index-filter
'git rm -r --cached --ignore-unmatch
.gitlab-ci.yml
"docs/proof of stake.md"
src/client/embedded/bootstrap/mining/
scripts/alphanet.sh
scripts/alphanet_constants.patch
scripts/alphanet_next.patch
scripts/zeronet.patch
scripts/delete_ci_image.sh'
--env-filter
- git filter-branch --prune-empty --env-filter
'if [ $GIT_COMMIT != "f42e9d12ac75d2876a4cf600d44976b7090d4533" ] ; then
export GIT_COMMITTER_NAME="$GIT_AUTHOR_NAME" ;
export GIT_COMMITTER_EMAIL="$GIT_AUTHOR_EMAIL" ;

321
docs/README.alphanet Normal file
View File

@ -0,0 +1,321 @@
Tezos (alphanet)
================
Welcome to the Tezos alphanet, which is a pre-release network for the
Tezos blockchain. Currently, the chain is reset every few weeks.
For news and support about the alphanet, please join IRC (`#tezos` on
freenode). Please, report bugs related to the alphanet on the IRC
channel before filling Github issues.
For more information about the project in general, see:
https://www.tezos.com/
How to join the alphanet ?
==========================
We provide two ways of joining the alphanet :
- use `docker` and prebuilt binaries
(recommended way, tested on windows/mac/linux)
- manual compilation and installation
(linux and mac only)
The `alphanet.sh` script
------------------------
The recommended way for running an up-to-date Tezos node connected to
the alphanet is to use `scripts/alphanet.sh`. Its only requirement is a
working installation of Docker:
https://www.docker.com/community-edition
First, you need to download the script:
```
wget https://raw.githubusercontent.com/tezos/tezos/alphanet/scripts/alphanet.sh
chmod +x alphanet.sh
```
You are now one step away from a working node:
```
./alphanet.sh start
```
This will launch a docker container running the various daemons that
form a working tezos node. The first launch might take a few minutes
to synchronize the chain.
On first launch the script will also create a cryptographic identity
(nicknamed `my_identity`) and provide you with free tezzies on a fresh
account (nicknamed `my_account`). You might check your balance with:
```
./alphanet.sh client get balance for my_account
```
On some circumstances the account creation might fail. If so, see
section "Known issues" below on how to force the account creation.
See `./alphanet.sh --help` for more informations about the script.
In particular see `./alphanet.sh client --help` and
`scripts/README.master` for more information about the client.
Every call to `alphanet.sh` will check for updates of the node and
will fail if your node is not up-to-date. For updating the node,
simply run:
```
./alphanet.sh restart
```
If you prefer to temporarily disable automatic updates, you just
have to set an environment variable:
```
export TEZOS_ALPHANET_DO_NOT_PULL=yes
```
Compilation from sources
------------------------
The `alphanet` branch in the tezos git repository will always contain
the up-to-date sources of the tezos-node required for running the
alphanet. See `docs/README.master` on how to compile it.
Once built, you might launch the a node by running:
```
./tezos-node identity generate 24.
./tezos-node run --rpc-addr localhost
```
By default this instance will store its data in `$HOME/.tezos-node`
and will listen to incoming peers on port 9732. It will also listen
to RPC requests on port 8732 (only from `localhost`). You might find
more options by running `./tezos-node config --help`.
If you want to stake (see below for more details), you will also have
to run:
```
./tezos-client launch daemon
```
That's all. For the rest of the document, to execute the example
commands, you will have to replace `./alphanet.sh client` by
`./tezos-client`.
How to observe the network ?
============================
The alphanet script provides a basic command `./alhpanet.sh head` that
allows you to see if your own node is synchronized.
The Tezos client also offers a lot of commands to introspect the state of
the node, and also to list and call the RPCs of the nodes.
Enthusiastic Tezos adopter fredcy has also developed a nice block explorer
for the alphanet. See [https://github.com/fredcy/tezos-client].
In an upcoming version, we will also provide an opt-in tool for node runners
that will allow us to provide a global monitoring panel of the alphanet.
How to obtain free Tez from the faucet contract ?
=================================================
The alphanet contains an ad-hoc faucet contract, that will generate
new tezzies for you to test. Obviously, this contract will not be
available outside of the test network.
First, if you don't have any cryptographic identity yet, you need to
generate one (replace `my_identity` with any name that suits you
best):
```
./alphanet.sh client gen keys "my_identity"
```
Then, you have to generate a new "free" account (replace `my_account`
with any name that suits you best and `my_identity` by the name used
in the previous command):
```
./alphanet.sh client originate free account "my_account" for "my_identity"
```
That's all. You might check your balance:
```
./alphanet.sh client get balance for "my_account"
```
If you want MORE tezzies, you need to generate as many free accounts as
you need (you should receive ꜩ100.000 per account) and then transfer
the tezzies into a single account. For instance:
```
./alphanet.sh client originate free account "my_alt_account" for "my_identity"
./alphanet.sh client transfer 100,000.00 from "my_alt_account" to "my_account" -fee 0.00
./alphanet.sh client forget contract "my_alt_account"
```
Note that the test network is kind enough to accept transactions
without fees...
How to play with smart-contracts ?
==================================
An advanced documentation of the smart contract language is in
`/src/proto/alpha/docs/language.md`
Some test contracts are in
`/tests/contracts/`
For details and examples, see:
http://www.michelson-lang.com/
How to stake on the alphanet ?
==============================
By default, the faucet of the alphanet (the one behind `./alphanet.sh
originate free account "my_account" for "my_identity"`) creates
contracts which are managed by `my_identity` but whose staking rights
are delegated to the baker of the block including the
origination. That way we are sure that staking rights are attributed
to an active baker.
But, nonetheless, you might claim your staking rights!
The following command returns the current delegate of a contract:
```
./alphanet.sh client get delegate for "my_account"
```
If it is one the following, it is indeed one of our "bootstrap"
contracts!
- `tz1YLtLqD1fWHthSVHPD116oYvsd4PTAHUoc`
- `tz1irovm9SKduvL3npv8kDM54PSWY5VJXoyz`
- `tz1UsgSSdRwwhYrqq7iVp2jMbYvNsGbWTozp`
- `tz1TwYbKYYJxw7AyubY4A9BUm2BMCPq7moaC`
- `tz1QWft73Zhj5VSA1sCuEi9HhDDJqywE6BtC`
You might change the delegate of a contract with a single command:
```
./alphanet.sh client set delegate for "my_account" to "my_identity"
```
You now have staking rights!
Well, almost.
You should wait.
A little bit.
At most two cycles. Which, on the alphanet is 128 blocks (something
around 2 hours). On the mainnet, this will be between 2 weeks and a
month.
But, to enforce your right a last step is required. When baking or
endorsing a block, a bond is taken out of the default account
associated to the public key of the delegate. Hence, in order to
stake, you must be provisioning for bond deposit.
```
./alphanet.sh client transfer 50,000.00 from "my_account" to "my_identity"
```
On the alphanet, a bond is ꜩ1000. Hence, with the previous command you
provisioned 50 bonds. If you want more, see section "How to obtain
free Tez from the faucet contract ?".
Now, you are settled. The `alphanet` docker image runs a baker daemon
and a endorser daemon, by default for all your keys.
To know if you staked, just run:
```
./alphanet.sh baker log
./alphanet.sh endorser log
```
You should see lines such as:
```
Injected block BLxzbB7PBW1axq for bootstrap5 after BLSrg4dXzL2aqq (level 1381, slot 0, fitness 00::0000000000005441, operations 21)
```
Or:
```
Injected endorsement for block 'BLSrg4dXzL2aqq' (level 1381, slot 3, contract bootstrap5) 'oo524wKiEWBoPD'
```
On the alphanet, rewards for staking are credited after 24 hours. The
reward for baking or endorsing a block is ꜩ150. The safety bond is
returned together with the reward.
To know when you will be allowed to stake in the current cycle, you
might try the following RPCs, where you replaced `tz1iFY8ads...` by
the appropriate value:
```
$ ./alphanet.sh client list known identities
my_identity: tz1iFY8aDskx9QGbgBy68SNAGgkc7AE2iG9H (public key known) (secret key known)
$ ./alphanet.sh client rpc call /blocks/head/proto/helpers/rights/mining/delegate/tz1iFY8aDskx9QGbgBy68SNAGgkc7AE2iG9H with '{}'
{ "ok":
[ { "level": 1400.000000, "priority": 2.000000,
"timestamp": "2017-05-19T03:21:52Z" },
... ] }
```
Known issues
============
Missing account `my_account`
----------------------------
The chain synchronization has not been optimized yet and the
`alphanet.sh` script might misdetect the end of the synchronization
step. If so, it will try to create your free account in an outdated
context and your new account will never be included in the chain.
To fix this, just wait for your node to be synchronized: for that run
the following command, in the middle of a (raw) json object, it should
display the date of the last block (which should not be too far in the
past):
```
./alphanet.sh head
```
Please note that the printed date is GMT, don't forget the time shift.
Then, you need to remove from the client state the non-existant
contract and regenerate a new one:
```
./alphanet.sh client forget contract "my_account"
./alphanet.sh client originate free account "my_account" for "my_identity"
```

10
docs/README.zeronet Normal file
View File

@ -0,0 +1,10 @@
Tezos (zeronet)
===============
The Tezos zeronet is a development network that might be broken
multiple times a day.
If you wish to experiment with Tezos we recommend you to test the `alphanet`,
which is a more stable test network.
In particular, we offer no support about the zeronet.

136
docs/proof of stake.md
View File

@ -1,136 +0,0 @@
# Proof-of-stake in Tezos: Michelson
## Introduction
This write-up intends to provide a more detailed description of the proof-of-stake mechanism in Michelson (Tezos' seed protocol) than is available in the white paper. It explains the rationale between the design decisions, highlights some tradeoffs and calls attention to potential weaknesses and concerns.
## Outline
Our proof-of-stake mechanism is based on a blockchain. We attempt to replicate Bitcoin's consensus properties without relying on proof-of-work. Instead of being discovered by miners through brute force search, the blocks are *forged* and *signed* by the participants in the network. We attempt to assign the right to sign the blocks randomly in proportion to the amount of tokens held. This isn’t necessarily because the party receiving the signing right has “something at stake” but rather because it acts as a reasonable Sybil prevention mechanism. This approach presents a few challenges:
1. What source of randomness can we use to assign signing rights?
2. What happens if the responsible party doesn’t sign a block ?
3. The old quip goes: “Time is nature's way to keep everything from happening all at once”. How do we go about that?
4. Since signatures are costless, how do we incentivize against forks that reorganize the blockchain?
5. Since blocks are cheap to create (it is the goal), how do we prevent DOS attacks that force nodes to waste time evaluating spurious forks?
If we can reasonably patch all of these issues, we may have a workable proof-of-stake scheme. It may not strictly dominate proof-of-work in all aspects, but it will better for some threat models and worse for others. Whether or not it is overall "better" or "worse" is ultimately an empirical question.
## A warning about complexity
Before we get started, I should disclose that the complexity of our approach gives me pause. Proof-of-work looks dead simple and yet has proven out to be a trove of gotchas (such as selfish-mining). With a complex system like the one I am about to describe, it is much more harduous to foresee all the potential problems and attacks. With hindsight, I realize I would be more comfortable with a mechanism offering a more patent security model. A verifiable reduction to PBFT would be ideal. Tendermint claims to do this, but I haven’t evaluated it and they have systematically failed to demonstrate reliable consensus in demonstrations. This may be an implementation issue or an issue with their design at large.
Fortunately, Tezos can upgrade its consensus mechanism, so all that is needed is for the current consensus mechanism to be sufficiently robust to cope long enough for a cleaner mechanism to replace it. A successful launch will give us ample funding to develop such a solution.
## Overview of our approach
There is some circular dependencies in the various parts which make up Michelson's proof-of-stake mechanism. For instance, the procedure by which we derive a random seed for assigning forging rights depends on the system's ability to resist censorship, but the latter cannot exist without random seeds. As a result, the reader may want to jump between the different sections or two read in two passes so as to resolve the dependencies.
### Cycle
Briefly speaking, the algorithm proceeds according to a cycle composed of a set number of blocks. The length of a cycle, in blocks, is a tunable parameter which we have yet to decide upon. We intend for a cycle to last between a few days and a few months. Shorter cycles offer better protection against censorship, while longer cycles provide a stronger consensus.
### Forging
At the beginning of a cycle, a random seed is derived from information revealed in the penultimate cycle. For each block in the cycle, we randomly assign "forging" rights priorities to stakeholders. For instance, for the 5th block in the cycle, the protocol may randomly pick stakeholder A and gives them the top priority for forging that block, then randomly pick stakeholder B and give them the second highest priority, and so on and so forth. Thus, each block in the cycle is associated with a list of stakeholders ordered by priority. This priority is reflected in the form of timing rules. The stakeholder with the top forging priority may create the block one minute after the previous block. If he doesn't do so, the stakeholder with the second highest forging priority may create the block two minutes after the previous block, etc.
### Endorsements
In addition to forging rights, the protocol randomly assigns endorsement rights. For each block, 16 endorsement rights are randomly assigned to stakeholders. An endorsement means that a select stakeholder signs a particular block. Those endorsements are then included in the block's children. The total number of signature in a chain is the criterion for selecting the longest chain.
Here's a quick explanation why signatures are needed. Suppose the next block is to be forged in priority by stakeholder A, followed by stakeholder B, while the block after that gives the first priority to B and the second to A. B could be tempted to create both blocks, linking them to each other in a form of "selfish forging". Signatures mitigate this greatly because endorsements for the first block would refer to the block mined by A, and B needs to include as many of these endorsements as possible for its block to hold weight.
Stakeholders are incentivized to collaborate to sign the same block in two ways. If a signer signs a block which doesn't end up being part of the blockchain, then they will miss out on receiving a reward, and the more signers agree on which block to sign, the higher the reward. They also receive a higher reward for higher priority blocks, to nudge them away from trying to hold out.
### Bonds and rewards
In proof-of-work, at a given time, a mining rig can only be used to mine children of a specific block. This financially incentivizes miners to commit to one particular branch. Cryptographic signatures on the other hand are very cheap, and thus a stakehoklder forging a block or signing an endorsment on our network could theoretically participate in two different branches. However, this can be detected by networks participants since in both cases the public key is the same.
Stakeholders maintain a pool of tokens which is used as collateral. Whenever a stakeholder forges a block or sign an endorsment, a portion of this pool is frozen for a period of time (we are targetting one year but may have a shorter cycle initially). The period of time is adjusted so that reimbursements fall on a predictable schedule in order to compress the size of the state needed. Reimbursements are made to the pool of tokens from which collateral is drawn. If a double signature is detected for the same block, but in a different branch, or the same endorsement, but for a different block, a miner can include a denunication in their block, which contains a proof of malfeasance. The bond is forfeited, and the miner receives a reward (of lower xvalue to the bond).
This effectively protects only against double signatures when the branches fork within the same cycle. If a fork happened ahead of the current cycle, "blocks" and "endorsements" are not meaningfully the same, and a stakeholder may get away with a double signature. However, large stakeholders who take part in the consensus algorithm will typically have a large amount of bonds "at stake" in the chain, making it unwise for them to cause trouble in the consensus.
### Randomness & rolls
In order to "randomly" determine how to assign mining a signing rights at the beginning of a cycle, we use a cryptographically secure PRNG seeded with a value computed at the end of the penultimate cycle. The seed is computed as follow. During a first cycle, block forgers commit to a secret random number by including its hash in their blocks. During the following cycle, they reveal their commitment under penalty of forfeiting the bond deposited for the block. All the revelead commitments are hashed together and a seed is derived by solving a related discrete logarithm problem.
To select a random stakeholder, we use a "follow-the-coin" strategy. This ensures that a malicious participant creating a fork by themselves cannot assign themselves signing and forging rights by shuffling around coins. Tracking every single coin would be inefficient. Instead, we track "rolls" of coin. A roll of coin represent a set of several coins bundled together. Sometimes transactions may break rolls, in which case the roll id goes into a LIFO queue and is reused as soon as enough loose coins are joined in a contract to form a roll. This means that a stake will alway be rounded down to the nearest number of rolls it represents.
### DDOS protection
Bitcoin's least appreciated strength is its resistance to DDOS attacks. When a peer advertises a better chain to a node, before beginning to even download the blocks, the amount of work can be assessed extremely quickly by looking at the block hashes. This doesn't mean further validation isn't warranted, the blocks may be invalid, but if they are, this is an extremely expensive attack to throw.
In contrast, in proof-of-stake, blocks are cheap to create and can take longer to validate. How do we prevent a scenario where peers flood us with invalid blocks advertising them as higher priority than the real chain. We take a variety of approaches.
First, we analyze blocks defensively, trying to reject invalid blocks as early as possible. This may not be as cheap as counting the number of 0s in a hash, andit may require downloading more data, but in the end, both are constant time operations.
Moreover, a valid, low priority, fork will have long time intervals between blocks. The network shell will simply refuse to validate blocks dated in the future. This prevents an adversary from forcing the evaluation of a trillion bock long forks for instance.
Furthermore, the network shell may blacklist IPs that relay invalid blocks. This is not ideal as it may lead to the blacklisting of TOR exit nodes and may not work well with IPv6. In the future, we could consider having peers purchase keys on the blockchain and require such keys to participate in the gossip network. This would make blacklisting / whitelisting work much better.
Last, but not least, we require the hash of each block to solve a small proof-of-work problem. It is calibrated so that creating a block should be roughly 1,000 times more expensive than validating it. The deadweight loss of this mild proof-of-work stamp is many order of magnitudes smaller than that of a regular proof-of-work consensus. It is not subject to a red queen effect: as hardware becomes better, it becomes cheaper to both generate and validate blocks.x
## Seed derivation
We can harden the seed derivation by making it computationally expensive to compute the seed. A simple approach would be to use many rounds of hashing, but this has the downside of requiring every party validating the ledger to perform the same computation. The solution to a preimage problem as in Bitcoin's proof-of-work is computationally hard but can be checked very cheaply. Unfortunately, those solutions aren't unique.
Instead we use a computationally hard problem where there exists a unique solution which can be checked inexpensively.
We first derive a 64 bit hash, x, out of the nonces revealed by the forgers. We then increment x until we find p, the smallest prime number greater or equal to x. The seed we seek is the discrete log of h(x) modulo p in base 2. This takes 32 bits of effort and about 1Gb of mmeory. A parameter which may be updated in further protocol changes.
The last block of a cycle must contain the solution to the problem.
### Informal checkpointing
Requiring regular, centralized checkpoints would defeat the purpose of a decentralized ledger. However, occasional checkpoints do have their use. After several months, the hash of a particular block in the blockchain should be considered largely a settled matter and may be discovered through social consensus. Certain attacks against proof-of-stake involve purchasing old wallet keys from former stakeholders. Such an attack, by its nature would be largely visible. If such a threat did arise, given the exceptional circumstances, the network participants can simply decide to protect themselves by picking a checkpoint. It's ad hoc, it's inelegant, but it works and it should be enough to thwart such an attack and even discourage it in the first place.
### Delegation
Each contract has two keys. A "manager" key for spending the funds, and a "delegate" key for all operations related to participations in the proof-of-stake protocol or the governance process. This has several advantages.
First, it permits specialization. Not every party holding a contract on the network is interested in participating directly in the proof-of-stake protocol or in network governance.
Second, it permits to keep private spending keys offline.
Third, delegate keys will be sticky to some extent. This prevents parties from changing their keys willy nilly which would weaken the ability to detect double signatures.
* The hash of the block
* An Ed25519 signature of the block
* A shell header
* A protocol header
The shell header is common to all protocol versions and can be understood by the network shell:
* A timestamp
* The hash of the preceding block
* The fitness score of the current chain
* A merkle tree of operation hashes, the semantics of which are opaque to the network shellx
The protocol header (specific to Michelson)
* A nonce used for a minimal proof-of-work stamp for DDOS purposes
* The current block height
* A list of denounciations
"Operations" act on the ledger to change its state. They are typically transactions, or new contract originations, but certain operations play a specific role in the proof-of-stake mechanism. They are
* Delegations
* Bond payments
* Endorsements
* Divulgments
## Cycles
The proof-of-stake algorithm works according to a set cycle. The lenght of the cycle (in block) is a tunable parameter, typically we intend to set it between a few days and a few months.

4
scripts/apply_patch.sh
View File

@ -21,12 +21,16 @@ case "$branch" in
sed -i s/TEZOS/TEZOS_ZERONET/ src/node/shell/distributed_db_message.ml
patch -p1 < scripts/alphanet_constants.patch
patch -p1 < scripts/zeronet.patch
cp README.md docs/README.master
cp docs/README.zeronet README.md
if has_git; then git commit -a -m "Zeronet: DO NOT MERGE" --author "Tezos CI <null@tezos.com>"; fi
echo "Done"
;;
alphanet)
sed -i s/TEZOS/TEZOS_ALPHANET/ src/node/shell/distributed_db_message.ml
patch -p1 < scripts/alphanet_constants.patch
cp README.md docs/README.master
cp docs/README.alphanet README.md
if has_git; then git commit -a -m "Alphanet: DO NOT MERGE" --author "Tezos CI <null@tezos.com>"; fi
echo "Done"
;;