diff --git a/.gitignore b/.gitignore index 5de7a10fe422234f934cca18f7fbf1ec1414c488..bbf3370bf11de6a1d5b7d7b3812d393eff4cea1c 100644 --- a/.gitignore +++ b/.gitignore @@ -24,6 +24,7 @@ __pycache__ /tezos-endorser-* /tezos-accuser-* /tezos-signer +/tezos-sandbox /scripts/opam-test-all.sh.DONE /scripts/create_genesis/src diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 10107d874aa57c29669dbdfaaa5808e15776069a..2d151c8ea2532f872630f25028a5d47262097fb6 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,6 +1,6 @@ variables: ## Please update `scripts/version.sh` accordingly - build_deps_image_version: ebc2de016e52e8b77f250df174512a793b2fb0e5 + build_deps_image_version: fdc1ab3f23d1601f00a2165e02fcd9fa3ddd8514 build_deps_image_name: registry.gitlab.com/tezos/opam-repository public_docker_image_name: docker.io/${CI_PROJECT_PATH} @@ -226,6 +226,41 @@ test:proto:sandbox: script: - dune build @runtest_sandbox +############################################################ +## Stage: run OCaml integration tests ## +############################################################ + +test:sandboxes:voting: + <<: *integration_definition + script: + - ROOT_PATH=$PWD/flextesa-voting-demo dune build @src/bin_flextesa/runtest_sandbox_voting_demo + artifacts: + paths: + - flextesa-voting-demo + expire_in: 1 day + when: on_failure + allow_failure: true # This test uses too much resources for GitLab's workers + +test:sandboxes:acc-baking: + <<: *integration_definition + script: + - ROOT_PATH=$PWD/flextesa-acc-sdb dune build @src/bin_flextesa/runtest_sandbox_accusations_simple_double_baking + artifacts: + paths: + - flextesa-acc-sdb + expire_in: 1 day + when: on_failure + +test:sandboxes:acc-endorsement: + <<: *integration_definition + script: + - ROOT_PATH=$PWD/flextesa-acc-sde dune build @src/bin_flextesa/runtest_sandbox_accusations_simple_double_endorsing + artifacts: + paths: + - flextesa-acc-sde + expire_in: 1 day + when: on_failure + ############################################################ ## Stage: run python integration tests ## ############################################################ @@ -589,72 +624,82 @@ opam:50:ocplib-ezresto: variables: package: ocplib-ezresto -opam:51:tezos-embedded-protocol-alpha: +opam:51:tezos-network-sandbox: + <<: *opam_definition + variables: + package: tezos-network-sandbox + +opam:52:tezos-embedded-protocol-alpha: <<: *opam_definition variables: package: tezos-embedded-protocol-alpha -opam:52:tezos-embedded-protocol-demo: +opam:53:tezos-embedded-protocol-demo: <<: *opam_definition variables: package: tezos-embedded-protocol-demo -opam:53:tezos-embedded-protocol-genesis: +opam:54:tezos-embedded-protocol-genesis: <<: *opam_definition variables: package: tezos-embedded-protocol-genesis -opam:54:tezos-shell: +opam:55:tezos-shell: <<: *opam_definition variables: package: tezos-shell -opam:55:tezos-endorser-alpha-commands: +opam:56:tezos-endorser-alpha-commands: <<: *opam_definition variables: package: tezos-endorser-alpha-commands -opam:56:tezos-client: +opam:57:tezos-client: <<: *opam_definition variables: package: tezos-client -opam:57:ocplib-ezresto-directory: +opam:58:ocplib-ezresto-directory: <<: *opam_definition variables: package: ocplib-ezresto-directory -opam:58:tezos-accuser-alpha: +opam:59:tezos-accuser-alpha: <<: *opam_definition variables: package: tezos-accuser-alpha -opam:59:tezos-endorser-alpha: +opam:60:flextesa: + <<: *opam_definition + variables: + package: flextesa + +opam:61:tezos-endorser-alpha: <<: *opam_definition variables: package: tezos-endorser-alpha -opam:60:tezos-accuser-alpha-commands: +opam:62:tezos-accuser-alpha-commands: <<: *opam_definition variables: package: tezos-accuser-alpha-commands -opam:61:tezos-baker-alpha: +opam:63:tezos-baker-alpha: <<: *opam_definition variables: package: tezos-baker-alpha -opam:62:tezos-signer: +opam:64:tezos-signer: <<: *opam_definition variables: package: tezos-signer -opam:63:tezos-node: +opam:65:tezos-node: <<: *opam_definition variables: package: tezos-node -opam:64:ocplib-json-typed-browser: +opam:66:ocplib-json-typed-browser: <<: *opam_definition variables: package: ocplib-json-typed-browser diff --git a/Makefile b/Makefile index fb45396e53ca559028d2ae5bda028e9a0b9b61c5..8a2b60e79fe350769cfddd1e48105faa98489796 100644 --- a/Makefile +++ b/Makefile @@ -78,7 +78,11 @@ doc-html: all doc-html-and-linkcheck: doc-html @${MAKE} -C docs all -build-test: +build-sandbox: + @dune build src/bin_flextesa/main.exe + @cp _build/default/src/bin_flextesa/main.exe tezos-sandbox + +build-test: build-sandbox @dune build @buildtest test: diff --git a/docs/tutorials/flextesa.rst b/docs/tutorials/flextesa.rst new file mode 100644 index 0000000000000000000000000000000000000000..4d6ca9f74aa2376b6171d77c972830707f2e8e12 --- /dev/null +++ b/docs/tutorials/flextesa.rst @@ -0,0 +1,173 @@ +Flexible Network Sandboxes +========================== + +Build +----- + +Use: + +:: + + make build-sandbox + +(or ``make build-test``). + +There are testing-only ``opam`` dependencies: ``dum`` and ``genspio`` +(``0.0.2``), make sure you have done ``make build-deps``. + +Usage +----- + +See ``./tezos-sandbox --help`` (or one can use +``_build/default/src/bin_flextesa/main.exe``). + +When running (semi-)interactive tests, it is recommended to wrap the +call with ``rlwrap`` or ``ledit``. + +Examples +-------- + +Mini-Network +~~~~~~~~~~~~ + +One can run a mini-network advancing fast with accusers, bakers, and +endorsers: + +:: + + rlwrap ./tezos-sandbox mini-network \ + --root-path /tmp/zz-mininet-test \ + --tezos-node-binary _build/default/src/bin_node/main.exe \ + --tezos-baker-alpha-binary _build/default/src/proto_alpha/bin_baker/main_baker_alpha.exe \ + --tezos-endorser-alpha-binary _build/default/src/proto_alpha/bin_endorser/main_endorser_alpha.exe \ + --tezos-accuser-alpha-binary _build/default/src/proto_alpha/bin_accuser/main_accuser_alpha.exe \ + --tezos-client-binary _build/default/src/bin_client/main_client.exe + +Once the network is started this test scenario becomes interactive: + +:: + + Flextesa.mininet: Please enter command: + +Just try ``h`` (or ``help``) to see the available commands. + +Double Endorsement Accusation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are 3 “accusation scenarios” so far, see +``./tezos-sandbox accusation --help``. For instance, the following command +starts a small 3-node network, forces one baker to endorse two +concurrent branches, and then makes another baker inject (and bake) the +double-endorsement-evidence operation. The option ``--base-port=20_000`` +tells ``tezos-sandbox`` to start allocating P2P/RPC ports from 20 000 and +``--pause-at-end=true`` tells ``tezos-sandbox`` to enter an interactive +command prompt at the end of the test to give a chance to explore the +sandbox before killing all the nodes. + +:: + + rlwrap ./tezos-sandbox accusations simple-double-endorsing \ + --root $PWD/double-endorsing-test \ + --base-port=20_000 \ + --pause-at-end=true + + +This test among other ones can run +`Kiln `__ +alongside the *Ꜩ-sandbox*, for instance: + +:: + + rlwrap ./tezos-sandbox accusations simple-double-endorsing --with-kiln + +See also the options ``--kiln-*`` for configuration, and the option +``--starting-level`` (since Kiln assumes a long-running blockchain +adding more, e.g. 40, bakes at the beginning of the test brings us to a +more “normal” state). + +Voting With a Ledger Nano S +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + **Note:** this requires a ``tezos-client`` with the changes from + https://gitlab.com/tezos/tezos/merge_requests/848. + +The voting test for now goes up to the last block before the protocol is +supposed to change to the election winner (see also +``./tezos-sandbox voting --help``). + +The test can use a Ledger Nano S as one of the voters (the test +automatically becomes **interactive** then because the user has to press +buttons on the device). + +Get an URI for your ledger (the test requires both the Wallet and Baking +apps): + +:: + + tezos-client list connected ledgers + +And use the URI (no need to import it) for the ``--with-ledger`` option: + +:: + + rlwrap ./tezos-sandbox voting ./src/bin_client/test/demo/ \ + --with-ledger "ledger://crouching-tiger-hidden-dragon/ed25519/0'/0'" \ + --serialize-proposals \ + --root $PWD/voting-test \ + --base-port=20_000 \ + --tezos-client-binary ../mr848/tezos-client \ + --pause-on-error=true + +The test becomes interactive and guides you through the interactions +with the ledger, e.g.: + +:: + + Flextesa.voting: + Ledger-prompt + + Setting up "ledger://crouching-tiger-hidden-dragon/ed25519/0'/0'" for + baking. The ledger should be showing the setup parameters (Address, + Main chain, HWMs). + + Please hit “✔” on the ledger. + +Implementation Considerations +----------------------------- + +``Running_processes`` is very high-level (actually agnostic to Tezos). +Most processes are actually calls to ``sh -c