{"id":13621466,"url":"https://github.com/0chain/0chain","last_synced_at":"2026-01-23T01:51:56.068Z","repository":{"id":36963699,"uuid":"114950878","full_name":"0chain/0chain","owner":"0chain","description":"Züs (formerly 0Chain) is a decentralized blockchain-based storage platform with no vendor lock-in and a 3-layer security - fragmentation, proxy re-encryption, and immutability. It has close to wire speed data performance, free reads, and is ideal for apps as well as backups, AI data, disaster recovery.","archived":false,"fork":false,"pushed_at":"2026-01-12T22:22:04.000Z","size":113675,"stargazers_count":123,"open_issues_count":187,"forks_count":62,"subscribers_count":28,"default_branch":"staging","last_synced_at":"2026-01-13T00:47:54.495Z","etag":null,"topics":["blockchain","decentralized-storage","high-performance","nft-store","private-sharing"],"latest_commit_sha":null,"homepage":"https://zus.network","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0chain.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2017-12-21T02:03:56.000Z","updated_at":"2025-12-17T16:17:19.000Z","dependencies_parsed_at":"2023-12-19T14:29:40.223Z","dependency_job_id":"76bbb6a3-a894-4c02-a8eb-db1d3fde7106","html_url":"https://github.com/0chain/0chain","commit_stats":null,"previous_names":[],"tags_count":113,"template":false,"template_full_name":null,"purl":"pkg:github/0chain/0chain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0chain%2F0chain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0chain%2F0chain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0chain%2F0chain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0chain%2F0chain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0chain","download_url":"https://codeload.github.com/0chain/0chain/tar.gz/refs/heads/staging","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0chain%2F0chain/sbom","scorecard":{"id":261,"data":{"date":"2025-08-11","repo":{"name":"github.com/0chain/0chain","commit":"f373ff0e3bb624a4da2de6cf079a71256ed1656d"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.8,"checks":[{"name":"Code-Review","score":2,"reason":"Found 1/4 approved changesets -- score normalized to 2","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Pinned-Dependencies","score":-1,"reason":"internal error: internal error: invalid Dockerfile","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":9,"reason":"license file detected","details":["Info: project has a license file: LICENSE.txt:0","Warn: project license file does not contain an FSF or OSI license."],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":10,"reason":"project is fuzzed","details":["Info: GoBuiltInFuzzer integration found: code/go/0chain.net/smartcontract/partitions/partitions_test.go:868","Info: GoBuiltInFuzzer integration found: code/go/0chain.net/smartcontract/partitions/partitions_test.go:913","Info: GoBuiltInFuzzer integration found: code/go/0chain.net/smartcontract/partitions/partitions_test.go:1000","Info: GoBuiltInFuzzer integration found: code/go/0chain.net/smartcontract/partitions/partitions_test.go:1094","Info: GoBuiltInFuzzer integration found: code/go/0chain.net/smartcontract/partitions/partitions_test.go:1149","Info: GoBuiltInFuzzer integration found: code/go/0chain.net/smartcontract/partitions/partitions_test.go:1210"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Info: jobLevel 'actions' permission set to 'read': .github/workflows/codeql-analysis.yml:23","Info: jobLevel 'contents' permission set to 'read': .github/workflows/codeql-analysis.yml:24","Warn: no topLevel permission defined: .github/workflows/automate-add-issue-in-project.yaml:1","Warn: no topLevel permission defined: .github/workflows/backup.yml:1","Warn: no topLevel permission defined: .github/workflows/benchmark-test.yml:1","Warn: no topLevel permission defined: .github/workflows/build-\u0026-publish-docker-image.yml:1","Warn: no topLevel permission defined: .github/workflows/build-integration-tests-images.yml:1","Warn: no topLevel permission defined: .github/workflows/codeql-analysis.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-0chain-config-tests.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-authorizer-tests.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-blobber-tests-01.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-blobber-tests-02.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-blobber-tests-03.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-blobber-tests-04.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-blobber-tests-05.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-blobber-tests-06.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-bridge-tests.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-byzantine-tests.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-fault-tolerance-tests.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-node-recovery-01-tests.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-node-recovery-02-tests.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-node-recovery-03-tests.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-standard-miner-tests.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-standard-sharder-tests.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-tests-flakiness.yaml:1","Warn: no topLevel permission defined: .github/workflows/conductor-tests.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-validators-tests.yml:1","Warn: no topLevel permission defined: .github/workflows/conductor-view-change-tests.yml:1","Warn: no topLevel permission defined: .github/workflows/config-change-0helm-pr.yaml:1","Warn: no topLevel permission defined: .github/workflows/config_change_alert.yaml:1","Warn: no topLevel permission defined: .github/workflows/install-conductor-testing-dependencies-on-ubuntu-server.yaml:1","Warn: no topLevel permission defined: .github/workflows/make-swagger.yaml:1","Warn: no topLevel permission defined: .github/workflows/manual-api-regressions.yml:1","Warn: no topLevel permission defined: .github/workflows/system_tests.yml:1","Warn: no topLevel permission defined: .github/workflows/unit-test.yml:1","Warn: no topLevel permission defined: .github/workflows/update-ct-machines.yml:1","Warn: no topLevel permission defined: .github/workflows/update-sprint-with-staging.yaml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/build-\u0026-publish-docker-image.yml:28"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"SAST","score":7,"reason":"SAST tool detected but not run on all commits","details":["Info: SAST configuration detected: CodeQL","Warn: 0 commits out of 28 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"16 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-jq35-85cj-fj4p","Warn: Project is vulnerable to: GO-2024-2512 / GHSA-xw73-rw38-6vjc","Warn: Project is vulnerable to: GO-2024-3005 / GHSA-v23v-6jw2-98fq","Warn: Project is vulnerable to: GHSA-4vq8-7jfc-9cvp","Warn: Project is vulnerable to: GO-2023-2046 / GHSA-ppjg-v974-84cm","Warn: Project is vulnerable to: GO-2024-2819 / GHSA-4xc9-8hmq-j652","Warn: Project is vulnerable to: GHSA-v9jh-j8px-98vq","Warn: Project is vulnerable to: GO-2024-2567 / GHSA-fqpg-rq76-99pq","Warn: Project is vulnerable to: GO-2024-2606 / GHSA-mrww-27vc-gghv","Warn: Project is vulnerable to: GO-2024-2491 / GHSA-xr7r-f8xq-vfvv","Warn: Project is vulnerable to: GO-2024-3110 / GHSA-jfvp-7x6p-h2pv","Warn: Project is vulnerable to: GO-2024-3321 / GHSA-v778-237x-gjrc","Warn: Project is vulnerable to: GO-2025-3487 / GHSA-hcg3-q754-cr77","Warn: Project is vulnerable to: GO-2024-3333","Warn: Project is vulnerable to: GO-2025-3503 / GHSA-qxp5-gwg8-xv66","Warn: Project is vulnerable to: GO-2025-3595 / GHSA-vvgc-356p-c3xw"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-14T12:21:22.680Z","repository_id":36963699,"created_at":"2025-08-14T12:21:22.680Z","updated_at":"2025-08-14T12:21:22.680Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28677714,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T01:00:35.747Z","status":"ssl_error","status_checked_at":"2026-01-23T01:00:19.529Z","response_time":144,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","decentralized-storage","high-performance","nft-store","private-sharing"],"created_at":"2024-08-01T21:01:06.733Z","updated_at":"2026-01-23T01:51:56.039Z","avatar_url":"https://github.com/0chain.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"            # Züs TestNet Setup with Docker Containers\n\n[![Build](https://github.com/0chain/0chain/actions/workflows/build-\u0026-publish-docker-image.yml/badge.svg)](https://github.com/0chain/0chain/actions/workflows/build-\u0026-publish-docker-image.yml)\n[![Test](https://github.com/0chain/0chain/actions/workflows/unit-test.yml/badge.svg)](https://github.com/0chain/0chain/actions/workflows/unit-test.yml)\n[![GoDoc](https://godoc.org/github.com/0chain/0chain?status.png)](https://godoc.org/github.com/0chain/0chain)\n[![codecov](https://codecov.io/gh/0chain/0chain/branch/staging/graph/badge.svg)](https://codecov.io/gh/0chain/0chain)\n\n## Table of Contents\n- [Züs Overview](#züs-overview)\n- [Changelog](#changelog)\n- [Initial Setup](#initial-setup)\n  - [Host Machine Network Setup](#host-machine-network-setup)\n  - [Directory Setup for Miners \u0026 Sharders](#directory-setup-for-miners-and-sharders)\n  - [Setup Network](#setup-network)\n  - [Building the Nodes](#building-the-nodes)\n  - [Configuring the Nodes](#configuring-the-nodes)\n  - [Starting the Nodes](#starting-the-nodes)\n  - [Check Chain Status](#check-chain-status)\n  - [Restarting the Nodes](#restarting-the-nodes)\n  - [Cleanup](#cleanup)\n- [Run 0chain on ec2 / vm / bare metal](https://github.com/0chain/0chain/blob/master/docker.aws/README.md)\n- [Run 0chain on ec2 / vm / bare metal over https](https://github.com/0chain/0chain/blob/master/https/README.md)\n- [Development](#development)\n  - [Installing msgp](#installing-msgp)\n  - [Dependencies for local compilation](#dependencies-for-local-compilation)\n  - [Debugging](#debugging)\n  - [Unit tests](#unit-tests)\n  - [Creating The Magic Block](#creating-the-magic-block)\n  - [Initial states](#initial-states)\n  - [Integration tests ](#integration-tests)\n    - [Architecture](#architecture)\n    - [Running Integration Tests](#running-integration-tests)\n    - [Running Standard Tests](#running-standard-tests)\n    - [Running complex scenario suites](#running-complex-scenario-suites)\n    - [Running Blobber Tests](#running-blobber-tests)\n    - [Adding new Tests](#adding-new-tests)\n    - [Supported Conductor Commands](#supported-conductor-commands)\n    - [Creating Custom Conductor Commands](#creating-custom-conductor-commands) \n  - [Benchmarks](#benchmarks)\n  - [Swagger documentation](#swagger-documentation)\n\n## Züs Overview \n[Züs](https://zus.network/) is a high-performance cloud on a fast blockchain offering privacy and configurable uptime. It is an alternative to traditional cloud S3 and has shown better performance on a test network due to its parallel data architecture. The technology uses erasure code to distribute the data between data and parity servers. Züs storage is configurable to provide flexibility for IT managers to design for desired security and uptime, and can design a hybrid or a multi-cloud architecture with a few clicks using [Blimp's](https://blimp.software/) workflow, and can change redundancy and providers on the fly.\n\nFor instance, the user can start with 10 data and 5 parity providers and select where they are located globally, and later decide to add a provider on-the-fly to increase resilience, performance, or switch to a lower cost provider.\n\nUsers can also add their own servers to the network to operate in a hybrid cloud architecture. Such flexibility allows the user to improve their regulatory, content distribution, and security requirements with a true multi-cloud architecture. Users can also construct a private cloud with all of their own servers rented across the globe to have a better content distribution, highly available network, higher performance, and lower cost.\n\n[The QoS protocol](https://medium.com/0chain/qos-protocol-weekly-debrief-april-12-2023-44524924381f) is time-based where the blockchain challenges a provider on a file that the provider must respond within a certain time based on its size to pass. This forces the provider to have a good server and data center performance to earn rewards and income.\n\nThe [privacy protocol](https://zus.network/build) from Züs is unique where a user can easily share their encrypted data with their business partners, friends, and family through a proxy key sharing protocol, where the key is given to the providers, and they re-encrypt the data using the proxy key so that only the recipient can decrypt it with their private key.\n\nZüs has ecosystem apps to encourage traditional storage consumption such as [Blimp](https://blimp.software/), a S3 server and cloud migration platform, and [Vult](https://vult.network/), a personal cloud app to store encrypted data and share privately with friends and family, and [Chalk](https://chalk.software/), a high-performance story-telling storage solution for NFT artists.\n\nOther apps are [Bolt](https://bolt.holdings/), a wallet that is very secure with air-gapped 2FA split-key protocol to prevent hacks from compromising your digital assets, and it enables you to stake and earn from the storage providers; [Atlus](https://atlus.cloud/), a blockchain explorer and [Chimney](https://demo.chimney.software/), which allows anyone to join the network and earn using their server or by just renting one, with no prior knowledge required.\n\n## Changelog\n[CHANGELOG.md](CHANGELOG.md)\n\n## Initial Setup\n\nDocker and Go must be installed to run the testnet containers. Get Docker from [here](https://docs.docker.com/engine/install/) and Go from [here](https://go.dev/doc/install). \n\n### Host Machine Network setup\n\n#### MacOS\n```bash\n./macos_network.sh\n```\n#### Windows\nRun powershell as administrator\n```powershell\n./windows_network.ps1\n```\n#### Ubuntu/WSL2\nRun the following script\n```bash\n./wsl_ubuntu_network_iptables.sh\n```\n### Directory Setup for Miners and Sharders\n\nIn the git/0chain run the following command\n\n```\n./docker.local/bin/init.setup.sh\n```\n\n### Setup Network\n\nSet up a network called testnet0 for each of these node containers to talk to each other.\n\n**_Note: The config file should be providing the IP address of the nodes as per the IP addresses in this network._**\n\n```\n./docker.local/bin/setup.network.sh\n```\n\n## Building the Nodes\n\n1. Open 5 terminal tabs. Use the first one for building the containers by being in git/0chain directory. Use the next 3 for 3 miners and be in the respective miner directories created above in docker.local. Use the 5th terminal and be in the sharder1 directory.\n\n   1.1) First build the base containers, zchain_build_base and zchain_run_base\n\n   ```\n   ./docker.local/bin/build.base.sh\n   ```\n2. Build mocks from the Makefile in the repo, from git/0chain directory run:\n   \n   ```\n    make build-mocks \n   ```\n   Note: Mocks have to be built once in the beginning. Building mocks require mockery and brew which can be installed from [here](https://docs.zus.network/guides/setup-a-blockchain/additional-tips-and-troubleshooting-for-mac#install-homebrew-and-mockery-on-mac-and-linux). \n\n3. Building the miners and sharders. From the git/0chain directory use\n\n   3.1) To build the miner containers\n\n   ```\n   ./docker.local/bin/build.miners.sh\n   ```\n\n   3.2) To build the sharder containers\n\n   ```\n   ./docker.local/bin/build.sharders.sh\n   ```\n\n   3.3) Syncing time (the host and the containers are being offset by a few seconds that throws validation errors as we accept transactions    that are within 5 seconds of creation). This step is needed periodically when you see the validation error.\n\n   ```\n   ./docker.local/bin/sync_clock.sh\n   ```\n\n## Configuring the nodes\n\n1. Use `./docker.local/config/0chain.yaml` to configure the blockchain properties. The default options are set up for running the blockchain fast in development.\n\n  1.1) If you want the logs to appear on the console - change `logging.console` from `false` to `true`\n\n  1.2) If you want the debug statements in the logs to appear - change `logging.level` from `\"info\"` to `\"debug\"`\n\n  1.3) If you want to change the block size, set the value of `server_chain.block.size`\n\n  1.4) If you want to adjust the network relay time, set the value of `network.relay_time`\n\n  1.5) If you want to turn off fees adjust `server_chain.smart_contract.miner` from `true` to `false`\n\n**_Note: Remove sharder72 and miner75 from docker.local/config/b0snode2_keys.txt and docker.local/config/b0mnode5_keys.txt respectively if you are joining to local network._**\n\n## Starting the nodes\n\n1. Starting the nodes. On each of the miner terminals use the commands (note the `..` at the beginning. This is because, these commands are run from within the `docker.local/\u003cminer/sharder|i\u003e` directories and the `bin` is one level above relative to these directories)\n\nStart sharder first because miners need the genesis magic block. On the sharder terminal, use\n\n```\n../bin/start.b0sharder.sh\n```\n\nWait till the cassandra is started and the sharder is ready to listen to requests.\n\nOn the respective miner terminal, use\n\n```\n../bin/start.b0miner.sh\n```\n## Check Chain Status\n\n1. Ensure the port mapping is all correct:\n\n```\ndocker ps\n```\n\nThis should display a few containers and should include containers with images miner1_miner, miner2_miner and miner3_miner, and they should have the ports mapped like \"0.0.0.0:7071-\u003e7071/tcp\"\n\n2. Confirming the servers are up and running. From a browser, visit\n\n- http://localhost:7071/_diagnostics\n\n- http://localhost:7072/_diagnostics\n\n- http://localhost:7073/_diagnostics\n\nto see the status of the miners.\n\nSimilarly, following links can be used to see the status of the sharders\n\n- http://localhost:7171/_diagnostics\n\n- http://localhost:7172/_diagnostics\n\n- http://localhost:7173/_diagnostics\n\n3. Connecting to redis servers running within the containers (you are within the appropriate miner directories)\n\nDefault redis (used for clients and state):\n\n```\n../bin/run.miner.sh redis redis-cli\n```\n\nRedis used for transactions:\n\n```\n../bin/run.miner.sh redis_txns redis-cli\n```\n\n4. Connecting to cassandra used in the sharder (you are within the appropriate sharder directories)\n\n```\n../bin/run.sharder.sh cassandra cqlsh\n```\n\n## Restarting the nodes\n\nTo reflect a change in config files 0chain.yaml and sc.yaml, just restart the miner or sharder to take the new configuration. If you're doing a code change locally or pulling updates from GitHub, you need to build.\n```\ngit pull\ndocker.local/bin/build.base.sh \u0026\u0026 docker.local/bin/build.sharders.sh \u0026\u0026 docker.local/bin/build.miners.sh\n```\nFor existing code and if you have tried running once, make sure there are no previous files and processes.\n```\ndocker stop $(docker ps -a -q)\ndocker.local/bin/clean.sh\ndocker.local/bin/init.setup.sh\ndocker.local/bin/sync_clock.sh\n```\nThen go to individual miner/sharder:\n```\n../bin/start.b0sharder.sh (start sharders first!)\n../bin/start.b0miner.sh\n```\n## Cleanup\n\n1. If you want to restart the blockchain from the beginning\n\n```\n./docker.local/bin/clean.sh\n```\n\nThis cleans up the directories within docker.local/miner* and docker.local/sharder*\n\n**_Note: this script can take a while if the blockchain generated a lot of blocks as the script deletes\nthe databases and also all the blocks that are stored by the sharders. Since each block is stored as a\nseparate file, deleting thousands of such files will take some time._**\n\n2. If you want to get rid of old unused docker resources:\n\n```\ndocker system prune\n```\n\n### Running on systems with SELinux enabled\n\nLibrary by `herumi` for working with BLS threshold signatures requires this flag turned on:\n\n```\nsetsebool -P selinuxuser_execheap 1\n```\n\nIf you are curious about the reasons for this, this thread sheds some light on the topic:\n\nhttps://github.com/herumi/xbyak/issues/9\n\n## Setting up Cassandra Schema\n\nThe following is no longer required as the schema is automatically loaded.\n\nStart the sharder service that also brings up the cassandra service. To run commands on cassandra, use the following command\n\n```\n../bin/run.sharder.sh cassandra cqlsh\n```\n\n1. To create zerochain keyspace, do the following\n\n```\n../bin/run.sharder.sh cassandra cqlsh -f /0chain/sql/zerochain_keyspace.sql\n```\n\n2. To create the tables, do the following\n\n```\n../bin/run.sharder.sh cassandra cqlsh -k zerochain -f /0chain/sql/txn_summary.sql\n```\n\n3. When you want to truncate existing data (use caution), do the following\n\n```\n../bin/run.sharder.sh cassandra cqlsh -k zerochain -f /0chain/sql/truncate_tables.sql\n```\n\n## Development\n\n### Installing msgp\n\nRun the following command to install the msgp tool:\n\n```sh\nmake install-msgp\n```\n\nWe are using [msgp](https://github.com/0chain/msgp) to encode/decode data that store in MPT, it is unnecessary\nto touch it unless there are data struct changes or new type of data structs need to store in MPT.\n\n\nWhen we need to add a new data struct to MPT, for example:\n\n```go\n//go:generate msgp -io=false -tests=false -v\npackage main\n\ntype Foo struct {\n\tName string\n}\n\n```\n\nNote:\n1. `msgp` does not support system type alias, so please do not use `datastore.Key` in MPT data struct, it is an alias of\nsystem type `string`.\n2. The `//go:generate msgp -io=false ...` works on file level, i.e, we only need to define it once a file,\nso please check if it is already defined before adding.\n\nThen run the following command from the project root to generate methods for serialization.\n\n```sh\nmake msgp\n```\n\nA new file will then be generated as {file}_gen.go in the same dir where the data struct is defined.\n\n### Dependencies for local compilation\n\nYou need to install `rocksdb` and `herumi/bls`, refer to `docker.local/build.base/Dockerfile.build_base` for necessary steps.\n\nFor local compilation it should be enough of `go build` from a submodule folder, e.g.\n```\ncd code/go/0chain.net/miner\ngo build\n```\n\nYou can pass tag `development` if you want to simulate n2n delays.\nAnd you also need tag `bn256` to build the same code as in production:\n```\ngo build -tags \"bn256 development\"\n```\n\n## Debugging\n\n### Bringing up the chain faster\n```bash\n./0chain_dev_deployment.sh\n```\n\n### Debug builds of 0chain\n\nIf you want to run a debug 0chain build you can follow the details contained in the\n[`0chain/local` folder](https://github.com/0chain/0chain/blob/debug_builds/local/README.md).\n\nOnly one miner and one sharder can be run on any single machine, so you will need at least\nthree machines to for a working 0chain.\n\n### Log files\n\nThe logs of the nodes are stored in log directory (/0chain/log on the container and docker.local/miner|sharder[n]/log in the host). The 0chain.log contains all the logs related to the protocol and the n2n.log contains all the node to node communication logs. The typical issues that need to be debugged is errors in the log, why certain things have not happened which requires reviewing the timestamp of a sequence of events in the network. Here is an example set of commands to do some debugging.\n\nFind errors in all the miner nodes (from git/0chain)\n\n```\ngrep ERROR docker.local/miner*/log/0chain.log\n```\n\nThis gives a set of errors in the log. Say an error indicates a problem for a specific block, say abc, then\n\n```\ngrep abc docker.local/miner*/log/0chain.log\n```\n\ngives all the logs related to block 'abc'\n\nTo get the start time of all the rounds\n\n```\ngrep 'starting round' docker.local/miner*/log/0chain.log\n```\n\nThis gives the start timestamps that can be used to correlate the events and their timings.\n\n## Unit tests\n\n 0chain unit tests verify the behaviour of individual parts of the program. A config for the base docker image can be provided on run to execute general unit tests.\n\n\n![unit testing uml](https://user-images.githubusercontent.com/65766301/120052862-0b4ffd00-c045-11eb-83c8-977dfdb3038e.png)\n\n\nNavigate to 0chain folder and run the script to build base docker image for unit testing :\n\n```\ncd 0chain\n./docker.local/bin/build.base.sh\n```\n\nThe base image includes all the dependencies required to test the 0chain code.\n\n### Running Tests\n\nNow run the script containing unit tests .\n\n```\n./docker.local/bin/unit_test.sh\n```\nOR to run the unit tests without the mocks,\n```\n./docker.local/bin/unit_test.sh --no-mocks \n```\n\nThe list of packages is optional, and if provided runs only the tests from those packages. The command for running unit tests with specific packages.\n\n```\n./docker.local/bin/unit_test.sh [\u003cpackages\u003e]\n```\n\n###  Testing Steps\n\nUnit testing happens over a series of steps one after the other.\n\n#### Step 1: FROM zchain_build_base\n\nThis `FROM`step does the required preparation and specifies the underlying OS architecture to use the build image. Here we are using the base image created in the build phase.\n\n#### Step 2: ENV SRC_DIR=/0chain\n\n The SRC_DIR  variable is a reference to a filepath which contains the code from your pull request. Here `/0chain` directory is specified as it is the one which was cloned.\n\n#### Step 3: Setting the `GO111Module` variable to `ON`\n\n`GO111MODULE` is an environment variable that can be set when using `go` for changing how Go imports packages. It was introduced to help ensure a smooth transition to the module system.\n\n`GO111MODULE=on` will force using Go modules even if the project is in your GOPATH. Requires `go.mod` to work.\n\n Note: The default behavior in Go 1.16 is now **GO111MODULE**=on\n\n#### Step 4: COPY ./code/go/0chain.net $SRC_DIR/go/0chain.net\n\nThis step copies the code from the source path to the destination path.\n\n#### Step 5: RUN cd $SRC_DIR/go/0chain.net \u0026\u0026  go mod download\n\nThe RUN command is an image build step which allows installing of application and packages requited for testing while the`go mod download` downloads the specific module versions you've specified in the `go.mod`file.\n\n#### Step 6: RUN cd $GOPATH/pkg/mod/github.com/valyala/gozstd@v1.5. \u0026\u0026     chmod -R +w . \u0026\u0026  make clean libzstd.a\n\nThis step runs the gozstd package and provides write permissions to the directory. gozstd which is a go wrapper for zstd (library) provides Go bindings for the libzstd C library. The `make clean` is run in the last to clean up the code and remove all the compiled object files from the source code\n\n#### Step 7: WORKDIR $SRC_DIR/go\n\nThis step defines the working directory for running unit tests which is (0chain/code/go/0chain.net/).For all the running general unit tests their code coverage will be defined in the terminal like this\n\n```\nok      0chain.net/chaincore/block      0.128s  coverage: 98.9% of statements\n```\n\nThe above output shows 98.9% of code statements was covered with tests.\n\n## Creating The Magic Block\n\nFirst build the magic block image.\n\n```\n./docker.local/bin/build.magic_block.sh\n```\n\nNext, set the configuration file. To do this edit the docker.local/build.magicBlock/docker-compose.yml file. On line 13 is a flag \"--config_file\" set it to the magic block configuration file you want to use.\n\nTo create the magic block.\n\n```\n./docker.local/bin/create.magic_block.sh\n```\n\nThe magic block and the dkg summary json files will appear in the docker.local/config under the name given in the configuration file.\n\nThe magic_block_file setting in the 0chain.yaml file needs to be updated with the new name of the magic block created.\n\nUpdate the miner config file, so it is set to the new dkg summaries. To do this edit the docker.local/build.miner/b0docker-compose.yml file. On line 55 is a flag \"--dkg_file\" set it to the dkg summary files created with the magic block.\n\n## Initial states\n\nThe balance for the various nodes is set up in a `initial_state.yaml` file.\nThis file is a list of node ids and token amounts.\n\nThe initial state yaml file is entered as a command line argument when\nrunning a sharder or miner, falling that the `0chain.yaml`\n`network.inital_states` entry is used to find the initial state file.\n\nAn example, that can be used with the preset ids, can be found at\n[0chain/docker.local/config/initial_state.yaml`](https://github.com/0chain/0chain/blob/master/docker.local/config/initial_state.yaml)\n\n\n\n## Benchmarks\nBenchmark 0chain smart-contract endpoints.\n\nRuns testing.Benchmark on each 0chain endpoint. The blockchain database used in these tests is constructed from the parameters in the benchmark.yaml. file. Smartcontracts do not (or should not) access tha chain so a populated MPT database is enough to give a realistic benchmark.\n\nMore info in [read.me](code/go/0chain.net/smartcontract/benchmark/main/readme.md)\n\n\n## Integration tests \n\nIntegration testing combines individual 0chain modules and test them as a group. Integration testing evaluates the compliance of a system for specific functional requirements and usually occurs after unit testing .\n\nFor integration testing, A conductor which is RPC(Remote Procedure Call) server is implemented to control behaviour of nodes .To know more about the conductor refer to the [conductor documentation](https://github.com/0chain/0chain/blob/master/code/go/0chain.net/conductor/README.md)\n\n### Architecture\nA conductor requires the nodes to be built in a certain order to control them during the tests. A config file is defined in [conductor.config.yaml](https://github.com/0chain/0chain/blob/master/docker.local/config/conductor.config.yaml) which contains important details such as details of all nodes used and custom commands used in integration testing.\n\n![integration testing](https://user-images.githubusercontent.com/65766301/120053178-6a624180-c046-11eb-8255-ac9b4e202e32.png)\n\nFor running multiple test cases,conductor uses a test suite which contains multiple sets of tests .A test suites can be categorized into 3 types of tests\n\n`standard tests` - Checks whether chain continue to function properly despite bad miner and sharder participants\n\n`view-change tests` - Checks whether addition and removal of nodes is working\n\n.`blobber tests` - Checks whether storage functions continue to work properly despite bad or lost blobber, and confirms expected storage function failures\n\nBelow is an example of conductor test suite.\n\n```\n# Under `enable` is the list of sets that will be run.\nenable:\n  - \"Miner down/up\"\n  - \"Blobber tests\"\n\n# Test sets defines the test cases it covers.\nsets:\n  - name: \"Miner down/up\"\n    tests:\n      - \"Miner: 50 (switch to contribute)\"\n      - \"Miner: 100 (switch to share)\"\n  - name: \"Blobber tests\"\n    tests:\n      - \"All blobber tests\"\n\n# Test cases defines the execution flow for the tests.\ntests:\n  - name: \"Miner: 50 (switch to contribute)\"\n    flow:\n    # Flow is a series of directives.\n    # The directive can either be built-in in the conductor\n    # or custom command defined in \"conductor.config.yaml\"\n      - set_monitor: \"sharder-1\" # Most directive refer to node by name, these are defined in `conductor.config.yaml`\n      - cleanup_bc: {} # A sample built-in command that triggers stop on all nodes and clean up.\n      - start: ['sharder-1']\n      - start: ['miner-1', 'miner-2', 'miner-3']\n      - wait_phase:\n          phase: 'contribute'\n      - stop: ['miner-1']\n      - start: ['miner-1']\n      - wait_view_change:\n          timeout: '5m'\n          expect_magic_block:\n            miners: ['miner-1', 'miner-2', 'miner-3']\n            sharders: ['sharder-1']\n  - name: \"Miner: 100 (switch to share)\"\n    flow:\n    ...\n  - name: \"All blobber tests\"\n    flow:\n      - command:\n          name: 'build_test_blobbers' # Sample custom command that executes `build_test_blobbers`\n    ...\n...\n```\n\n### Running Integration Tests\n\n#### Prerequisites\n\nDocker and Git must be installed to run the tests .\n\nInstall Git using the following command:\n\n```\nsudo apt install git\n```\n\nDocker installation instructions can be found [here](https://docs.docker.com/engine/install/).\n\n#### Cloning the repository and Building Base Image\n\nClone the 0chain repository:\n\n```\ngit clone https://github.com/0chain/0chain.git\n```\n\nBuild miner docker image for integration test\n\n```\n(cd 0chain \u0026\u0026 ./docker.local/bin/build.miners-integration-tests.sh)\n```\n\nBuild sharder docker image for integration test\n\n```\n(cd 0chain \u0026\u0026 ./docker.local/bin/build.sharders-integration-tests.sh)\n```\n\nNOTE: The miner and sharder images are designed for integration tests only. If wanted to run chain normally, rebuild the original images.\n\n```\n(cd 0chain \u0026\u0026 ./docker.local/bin/build.sharders.sh \u0026\u0026 ./docker.local/bin/build.miners.sh)\n```\n\nConfirm that view change rounds are set to 50 on `0chain/docker.local/config.yaml`\n\n```\n    start_rounds: 50\n    contribute_rounds: 50\n    share_rounds: 50\n    publish_rounds: 50\n    wait_rounds: 50\n```\n\n### Running standard tests\n\nRun miners test\n\n```\n(cd 0chain \u0026\u0026 ./docker.local/bin/start.conductor.sh miners)\n```\n\nRun sharders test\n\n```\n(cd 0chain \u0026\u0026 ./docker.local/bin/start.conductor.sh sharders)\n```\n\n### Running complex scenario suites\n\n1. These 2 scripts should be run with `view_change: false` in `0chain/docker.local/config.yaml`\n  1.1. `(cd 0chain \u0026\u0026 ./docker.local/bin/start.conductor.sh no-view-change.byzantine)`\n  1.2. `(cd 0chain \u0026\u0026 ./docker.local/bin/start.conductor.sh no-view-change.fault-tolerance)`\n2. Set `view_change: true` in `0chain/docker.local/config.yaml` for the following 2 scripts\n  2.1. `(cd 0chain \u0026\u0026 ./docker.local/bin/start.conductor.sh view-change.byzantine)`\n  2.2. `(cd 0chain \u0026\u0026 ./docker.local/bin/start.conductor.sh view-change.fault-tolerance*)`\n\n### Running blobber tests\n\nRefer to [conductor documentation](https://github.com/0chain/0chain/blob/master/code/go/0chain.net/conductor/README.md#blobber)\n\n### Adding new Tests\n\nNew tests can be easily added  to the conductor check [Updating conductor tests](https://github.com/0chain/0chain/blob/master/code/go/0chain.net/conductor/README.md#updating-conductor-tests) in the conductor documentation for more information.\n\n### Enabling or Disabling Tests\n\nCheck [Temporarily disabling tests](https://github.com/0chain/0chain/blob/master/code/go/0chain.net/conductor/README.md#temporarily-disabling-tests) in the conductor documentation for more information\n\n### Supported Conductor Commands\nCheck the [supported directives](https://github.com/0chain/0chain/blob/master/code/go/0chain.net/conductor/README.md#supported-directives) in the conductor documentation for more information.\n\n### Creating Custom Conductor Commands\n\nCheck [Custom Commands](https://github.com/0chain/0chain/blob/master/code/go/0chain.net/conductor/README.md#custom-commands) in the conductor documentation for more information\n\n## Swagger documentation\n\nTo generate swagger documentation you need go-swagger installed, visit https://goswagger.io/install.html for details.\n\nYou then need to run the makefile\n```bash\nmake swagger\n```\nThe documentation will be in `docs/swagger.md` and `docs/swagger.yaml`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0chain%2F0chain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0chain%2F0chain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0chain%2F0chain/lists"}