|
1 | | -# Filecoin (venus) |
| 1 | +<p align="center"> |
| 2 | + <a href="https://venus.filecoin.io/Overview.html" title="Filecoin Docs"> |
| 3 | + <img src="documentation/images/venus_logo_big2.jpg" alt="Project Venus Logo" width="330" /> |
| 4 | + </a> |
| 5 | +</p> |
2 | 6 |
|
3 | | -[](https://circleci.com/gh/filecoin-project/venus) |
4 | | -[](https://github.com/filecoin-project/venus/releases/latest) |
5 | | -[](https://github.com/filecoin-project/venus/releases) |
6 | | -[](https://github.com/filecoin-project/venus/releases) |
7 | 7 |
|
8 | | -venus is an implementation of the Filecoin Distributed Storage Network. For more details about Filecoin, checkout the [Filecoin Spec](https://spec.filecoin.io). |
9 | 8 |
|
10 | | -venus was the first Filecoin implementation originially initiated and developed by Protocol Labs, and now is maintained by the Filecoin community. See [maintenance](#maintenance) for more information. |
| 9 | +<h1 align="center">Project Venus - 启明星</h1> |
11 | 10 |
|
12 | | -__Questions or problems with venus? [Ask the community first](#community)__. Your problem may already be solved. |
| 11 | +<p align="center"> |
| 12 | + <a href="https://circleci.com/gh/filecoin-project/venus"><img src="https://circleci.com/gh/filecoin-project/venus.svg?style=svg"></a> |
| 13 | + <a href="https://github.com/filecoin-project/venus/releases/latest"><img src="https://img.shields.io/endpoint.svg?color=brightgreen&style=flat&logo=GitHub&url=https://raw.githubusercontent.com/filecoin-project/go-filecoin-badges/master/user-devnet.json"></a> |
| 14 | + <a href="https://github.com/filecoin-project/venus/releases"><img src="https://img.shields.io/endpoint.svg?color=blue&style=flat&logo=GitHub&url=https://raw.githubusercontent.com/filecoin-project/go-filecoin-badges/master/nightly-devnet.json" /></a> |
| 15 | + <a href="https://github.com/filecoin-project/venus/releases"><img src="https://img.shields.io/endpoint.svg?color=brightgreen&style=flat&logo=GitHub&url=https://raw.githubusercontent.com/filecoin-project/go-filecoin-badges/master/staging-devnet.json" /></a> |
| 16 | + <br> |
| 17 | +</p> |
13 | 18 |
|
14 | | -## Table of Contents |
15 | | -<!-- |
16 | | - TOC generated by https://github.com/thlorenz/doctoc |
17 | | - Install with `npm install -g doctoc`. |
18 | | - Regenerate with `doctoc README.md`. |
19 | | - It's ok to edit manually if you don't have/want doctoc. |
20 | | - --> |
21 | | -<!-- START doctoc generated TOC please keep comment here to allow auto update --> |
22 | | -<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --> |
| 19 | +Venus is an implementation of the Filecoin Distributed Storage Network. For more details about Filecoin, check out the [Filecoin Spec](https://spec.filecoin.io). |
23 | 20 |
|
| 21 | +## Building & Documentation |
24 | 22 |
|
25 | | -- [What is Filecoin?](#what-is-filecoin) |
26 | | -- [Install](#install) |
27 | | - - [System Requirements](#system-requirements) |
28 | | - - [Install from Source](#install-from-source) |
29 | | - - [Install Go](#install-go) |
30 | | - - [Install Dependencies](#install-dependencies) |
31 | | - - [Build and run tests](#build-and-run-tests) |
32 | | -- [Usage](#usage) |
33 | | - - [Advanced usage](#advanced-usage) |
34 | | - - [Setting up a localnet](#setting-up-a-localnet) |
35 | | -- [Contributing](#contributing) |
36 | | -- [Community](#community) |
37 | | -- [License](#license) |
| 23 | +For instructions on how to build, install and join a Venus mining pool, please visit [here](https://venus.filecoin.io/Using-venus-Shared-Modules.html). |
38 | 24 |
|
39 | | -<!-- END doctoc generated TOC please keep comment here to allow auto update --> |
| 25 | +## Venus architecture |
40 | 26 |
|
41 | | -## What is Filecoin? |
42 | | -Filecoin is a decentralized storage network that turns the world’s unused storage into an algorithmic market, creating a permanent, decentralized future for the web. |
43 | | -**Miners** earn the native protocol token (also called “Filecoin”) by providing data storage and/or retrieval. |
44 | | -**Clients** pay miners to store or distribute data and to retrieve it. |
45 | | -Check out the [Filecoin website](https://filecoin.io/) and [Filecoin Documentation](https://docs.filecoin.io/) for more. |
| 27 | +With ideas like security, ease of use and distributed mining pool in mind, deployment of a mining operation using Venus is quite different from one using [Lotus](https://github.com/filecoin-project/lotus). Details of mining architecture can be found [here](https://venus.filecoin.io/Overview.html#architecture). |
46 | 28 |
|
47 | | -## Install |
| 29 | +## Related modules |
48 | 30 |
|
49 | | -👋 Welcome to venus! |
| 31 | +Venus loosely describes a collection of modules that work together to realize a fully featured Filecoin implementation. List of stand-alone venus modules repos can ben found [here](https://venus.filecoin.io/Using-venus-Shared-Modules.html#introducing-venus-modules), each assuming different roles in the functioning of Filecoin. |
50 | 32 |
|
51 | | -This README outlines the basics for building and running venus. |
52 | | -**For more background, configuration, and troubleshooting information check out the [venus Docs](https://go.filecoin.io/)**. |
| 33 | +## Contribute |
53 | 34 |
|
54 | | -### System Requirements |
| 35 | +Lotus is a universally open project and welcomes contributions of all kinds: code, docs, and more. However, before making a contribution, we ask you to heed these recommendations: |
55 | 36 |
|
56 | | -venus can build and run on most Linux and MacOS systems. |
57 | | -Windows is not yet supported. |
| 37 | +1. If the proposal entails a protocol change, please first submit a [Filecoin Improvement Proposal](https://github.com/filecoin-project/FIPs). |
| 38 | +2. If the change is complex and requires prior discussion, [open an issue](https://github.com/filecoin-project/venus/issues) or a [discussion](https://github.com/filecoin-project/venus/discussions) to request feedback before you start working on a pull request. This is to avoid disappointment and sunk costs, in case the change is not actually needed or accepted. |
| 39 | +3. Please refrain from submitting PRs to adapt existing code to subjective preferences. The changeset should contain functional or technical improvements/enhancements, bug fixes, new features, or some other clear material contribution. Simple stylistic changes are likely to be rejected in order to reduce code churn. |
58 | 40 |
|
59 | | -A validating node can run on most systems with at least 8GB of RAM. |
60 | | -A mining node requires significant RAM and GPU resources, depending on the sector configuration to be used. |
| 41 | +When implementing a change: |
61 | 42 |
|
62 | | - |
63 | | -### Install from Source |
64 | | -Clone this git repository to your machine: |
65 | | - |
66 | | -```sh |
67 | | -mkdir -p /path/to/filecoin-project |
68 | | -git clone https://github.com/filecoin-project/venus.git /path/to/filecoin-project/venus |
69 | | -``` |
70 | | - |
71 | | -#### Install Go |
72 | | - |
73 | | -The build process for venus requires [Go](https://golang.org/doc/install) >= v1.15.5 |
74 | | - |
75 | | -> Installing Go for the first time? We recommend [this tutorial](https://www.ardanlabs.com/blog/2016/05/installing-go-and-your-workspace.html) which includes environment setup. |
76 | | -
|
77 | | -Due to our use of `cgo`, you'll need a C compiler to build venus whether you're using a prebuilt library or building it yourself from source. |
78 | | -If you want to use `gcc` (e.g. `export CC=gcc`) when building venus, you will need to use v7.4.0 or higher. |
79 | | - |
80 | | -The build process will download a static library containing the [Filecoin proofs implementation](https://github.com/filecoin-project/rust-fil-proofs) (which is written in Rust). |
81 | | - |
82 | | -> If instead you wish to build proofs from source, you'll need (1) Rust development environment and (2) to set the environment variable `FFI_BUILD_FROM_SOURCE=1`. |
83 | | -More info at [filecoin-ffi](https://github.com/filecoin-project/filecoin-ffi). |
84 | | - |
85 | | -#### Install Dependencies |
86 | | - |
87 | | -First install components |
88 | | - |
89 | | -```sh |
90 | | -sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm; sudo yum install -y git gcc bzr jq pkgconfig clang llvm mesa-libGL-devel opencl-headers ocl-icd ocl-icd-devel hwloc-devel |
91 | | -``` |
92 | | - |
93 | | -Initialize build dependencies. |
94 | | - |
95 | | -```sh |
96 | | -make deps |
97 | | -``` |
98 | | - |
99 | | -Note: The first time you run `deps` can be **slow** as very large parameter files are either downloaded or generated locally in `/var/tmp/filecoin-proof-parameters`. |
100 | | -Have patience; future runs will be faster. |
101 | | - |
102 | | -#### Build and run tests |
103 | | - |
104 | | -```sh |
105 | | -# First, build the binary |
106 | | -make |
107 | | - |
108 | | -# Then, run the unit tests. |
109 | | -go run ./build test |
110 | | - |
111 | | -# Build and test can be combined! |
112 | | -go run ./build best |
113 | | -``` |
114 | | - |
115 | | -Other handy build commands include: |
116 | | - |
117 | | -```sh |
118 | | -# Check the code for style and correctness issues |
119 | | -go run ./build lint |
120 | | - |
121 | | -# Run different categories of tests by toggling their flags |
122 | | -go run ./build test -unit=false -integration=true -functional=true |
123 | | - |
124 | | -# Test with a coverage report |
125 | | -go run ./build test -cover |
126 | | - |
127 | | -# Test with Go's race-condition instrumentation and warnings (see https://blog.golang.org/race-detector) |
128 | | -go run ./build test -race |
129 | | - |
130 | | -# Deps, Lint, Build, Test (any args will be passed to `test`) |
131 | | -go run ./build all |
132 | | -``` |
133 | | - |
134 | | -Note: Any flag passed to `go run ./build test` (e.g. `-cover`) will be passed on to `go test`. |
135 | | - |
136 | | -If you have **problems with the build**, please consult the [Troubleshooting](https://go.filecoin.io/go-filecoin-tutorial/Troubleshooting-&-FAQ.html) section of the [venus Documentation](https://go.filecoin.io/). |
137 | | - |
138 | | -## Usage |
139 | | - |
140 | | -For a complete step-by-step tutorial, see [Getting Started](https://go.filecoin.io/venus-tutorial/Getting-Started.html). |
141 | | - |
142 | | -#### Quick start: |
143 | | - |
144 | | -```sh |
145 | | -# Remove any existing symlink to a repo directory |
146 | | -rm -rf ~/.venus |
147 | | - |
148 | | -# Initialize a new repository, Start the daemon. It will block until it connects to at least one bootstrap peer. |
149 | | -./venus daemon #mainnet |
150 | | -./venus daemon --network cali #calibration |
151 | | -``` |
152 | | - |
153 | | -Your node should now be connected to some peers, and begin downloading and validating the blockchain. |
154 | | - |
155 | | -Open a new terminal to interact with your node: |
156 | | - |
157 | | -```sh |
158 | | -# Print the node's connection information |
159 | | -./venus swarm id |
160 | | - |
161 | | -# Show chain sync status |
162 | | -./venus chain status |
163 | | -``` |
164 | | - |
165 | | -To see a full list of commands, run `./venus --help`. |
166 | | - |
167 | | -## Contributing |
168 | | - |
169 | | -We ❤️ all our contributors; this project wouldn’t be what it is without you! If you want to help out, please see [CONTRIBUTING.md](CONTRIBUTING.md). |
170 | | - |
171 | | -Check out the [venus code overview](CODEWALK.md) for a brief tour of the code. |
172 | | - |
173 | | -## Community |
174 | | - |
175 | | -Here are a few places to get help and connect with the Filecoin community: |
176 | | -- [venus Documentation](http://go.filecoin.io/) — for tutorials, troubleshooting, and FAQs |
177 | | -- The `#fil-venus` channel on [Filecoin Project Slack](https://filecoinproject.slack.com/messages/CEHHJNJS3/) or [Matrix/Riot](https://riot.im/app/#/room/#fil-dev:matrix.org) - for live help and some dev discussions |
178 | | -- [Filecoin Community Forum](https://discuss.filecoin.io) - for talking about design decisions, use cases, implementation advice, and longer-running conversations |
179 | | -- [GitHub issues](https://github.com/filecoin-project/venus/issues) - to report bugs, and view or contribute to ongoing development. |
180 | | -- [Filecoin Specification](https://github.com/filecoin-project/specs) - how Filecoin is supposed to work |
181 | | - |
182 | | -Looking for even more? See the full rundown at [filecoin-project/community](https://github.com/filecoin-project/community). |
183 | | - |
184 | | -## Maintenance |
185 | | - |
186 | | -Venus (previously called `go-filecoin`) is now maintained by [IPFS-Force Community](https://github.com/ipfs-force-community) |
187 | | - |
188 | | -Maintainers: @steven004, @diwufeiwen, @hunjixin, @felix00000 |
189 | | - |
190 | | -This repo is open for anyone to submit issues and PRs. |
| 43 | +1. Adhere to the standard Go formatting guidelines, e.g. [Effective Go](https://golang.org/doc/effective_go.html). Run `go fmt`. |
| 44 | +2. Stick to the idioms and patterns used in the codebase. Familiar-looking code has a higher chance of being accepted than eerie code. Pay attention to commonly used variable and parameter names, avoidance of naked returns, error handling patterns, etc. |
| 45 | +3. Comments: follow the advice on the [Commentary](https://golang.org/doc/effective_go.html#commentary) section of Effective Go. |
| 46 | +4. Minimize code churn. Modify only what is strictly necessary. Well-encapsulated changesets will get a quicker response from maintainers. |
| 47 | +5. Lint your code with [`golangci-lint`](https://golangci-lint.run) (CI will reject your PR if unlinted). |
| 48 | +6. Add tests. |
| 49 | +7. Title the PR in a meaningful way and describe the rationale and the thought process in the PR description. |
| 50 | +8. Write clean, thoughtful, and detailed [commit messages](https://chris.beams.io/posts/git-commit/). This is even more important than the PR description, because commit messages are stored _inside_ the Git history. One good rule is: if you are happy posting the commit message as the PR description, then it's a good commit message. |
191 | 51 |
|
192 | 52 | ## License |
193 | 53 |
|
194 | | -The Filecoin Project is dual-licensed under Apache 2.0 and MIT terms: |
| 54 | +This project is dual-licensed under [Apache 2.0](https://github.com/filecoin-project/lotus/blob/master/LICENSE-APACHE) and [MIT](https://github.com/filecoin-project/lotus/blob/master/LICENSE-MIT). |
195 | 55 |
|
196 | | -- Apache License, Version 2.0, ([LICENSE-APACHE](https://github.com/filecoin-project/venus/blob/master/LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0) |
197 | | -- MIT license ([LICENSE-MIT](https://github.com/filecoin-project/venus/blob/master/LICENSE-MIT) or http://opensource.org/licenses/MIT) |
0 commit comments