Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Docs: Update README.md to be more concise #6099

Merged
merged 3 commits into from
Oct 22, 2024
Merged

Docs: Update README.md to be more concise #6099

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
85c9562
Update README.md
Pcharlesme Aug 10, 2024
4946c17
Update README.md
Pcharlesme Sep 5, 2024
9effa77
Update README.md
Pcharlesme Sep 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
205 changes: 87 additions & 118 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,204 +1,173 @@
| rel/stable <br> [![CircleCI](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fstable.svg?style=svg)](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fstable) | rel/beta <br> [![CircleCI](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fbeta.svg?style=svg)](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fbeta) | rel/nightly <br> [![CircleCI](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fnightly.svg?style=svg)](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fnightly) |
| --- | --- | --- |

# go-algorand
| **Branch** | **Build Status** |
| --------------- | ---------------- |
| **rel/stable** | [![CircleCI](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fstable.svg?style=svg)](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fstable) |
| **rel/beta** | [![CircleCI](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fbeta.svg?style=svg)](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fbeta) |
| **rel/nightly** | [![CircleCI](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fnightly.svg?style=svg)](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fnightly) |

Algorand's official implementation in Go.

Algorand is a permissionless, pure proof-of-stake blockchain that delivers
decentralization, scalability, security, and transaction finality.
**Algorand's** official implementation in Go.

Algorand is a permissionless, pure proof-of-stake blockchain that delivers decentralization, scalability, security, and transaction finality.

## Getting Started

Our [developer website][developer site url] has the most up to date information
about using and installing the Algorand platform.
Visit our [developer website](https://developer.algorand.org/) for the most up-to-date information about using and installing the Algorand platform.

## Building from source
## Building from Source

Development is done using the [Go Programming Language](https://golang.org/).
The version of go is specified in the project's [go.mod](go.mod) file. This document assumes that you have a functioning
environment setup. If you need assistance setting up an environment please visit
the [official Go documentation website](https://golang.org/doc/).
Development is done using the Go Programming Language. The Go version is specified in the project's [go.mod](go.mod) file. This document assumes you have a functioning environment set up. If you need assistance setting up an environment, please visit the [official Go documentation website](https://golang.org/doc/).

### Linux / OSX

We currently strive to support Debian-based distributions with Ubuntu 20.04
being our official release target.
Building on Arch Linux works as well.
Our core engineering team uses Linux and OSX, so both environments are well
supported for development.
We currently strive to support Debian-based distributions, with Ubuntu 20.04 as our official release target. Building on Arch Linux also works well. Our core engineering team uses Linux and OSX, so both environments are well-supported for development.

**OSX Only**: [Homebrew (brew)](https://brew.sh) must be installed before continuing. [Here](https://docs.brew.sh/Installation) are the installation requirements.

OSX only: [Homebrew (brew)](https://brew.sh) must be installed before
continuing. [Here](https://docs.brew.sh/Installation) are the installation
requirements.
### Initial Environment Setup

Initial environment setup:
```bash
git clone https://github.com/algorand/go-algorand
cd go-algorand
./scripts/configure_dev.sh
./scripts/buildtools/install_buildtools.sh
```

At this point, you are ready to build go-algorand. We use `make` and have a
number of targets to automate common tasks.
At this point, you are ready to build go-algorand. We use `make` and have several targets to automate common tasks.

### Build

#### build
```bash
make install
```

#### test
### Test

```bash
# unit tests
# Unit tests
make test

# integration tests
# Integration tests
make integration
```

#### style and checks
### Style and Checks

```bash
make fmt
make lint
make fix
make vet
```
or alternatively

Alternatively, run:

```bash
make sanity
```

### Running a node
## Running a Node

Once the software is built, you'll find binaries in `${GOPATH}/bin`, and a data directory will be initialized at `~/.algorand`. Start your node with:

```bash
${GOPATH}/bin/goal node start -d ~/.algorand
```

Once the software is built you'll find binaries in `${GOPATH}/bin`, and a data
directory will be initialized at `~/.algorand`. Start your node with
`${GOPATH}/bin/goal node start -d ~/.algorand`, use `${GOPATH}/bin/carpenter -d
~/.algorand` to see activity. Refer to the [developer website][developer site
url] for how to use the different tools.
Use:

```bash
${GOPATH}/bin/carpenter -d ~/.algorand
```

to see activity. Refer to the [developer website](https://developer.algorand.org/) for instructions on using different tools.

### Providing Your Own Data Directory

You can run a node out of other directories than `~/.algorand` and join networks other than mainnet. Just make a new directory and copy the `genesis.json` file for the network into it. For example:

#### Providing your own data directory
You can run a node out of other directories than `~/.algorand` and join networks
other than mainnet. Just make a new directory and copy into it the
`genesis.json` file for the network. For example:
```bash
mkdir ~/testnet_data
cp installer/genesis/testnet/genesis.json ~/testnet_data/genesis.json
${GOPATH}/bin/goal node start -d ~/testnet_data
```
Genesis files for mainnet, testnet, and betanet can be found in
`installer/genesis/`.

Genesis files for mainnet, testnet, and betanet can be found in `installer/genesis/`.

## Contributing

Please refer to our [CONTRIBUTING](CONTRIBUTING.md) document.


## Project Layout

`go-algorand` is split into various subsystems containing various packages.
`go-algorand` is organized into various subsystems and packages:

### Core

Provides core functionality to the `algod` and `kmd` daemons, as well as other tools and commands:

- `crypto` contains the cryptographic constructions we're using for hashing,
signatures, and VRFs. There are also some Algorand-specific details here
about spending keys, protocols keys, one-time-use signing keys, and how they
relate to each other.
- `config` holds configuration parameters. These include parameters used
locally by the node as well as parameters that must be agreed upon by the
protocol.
- `data` defines various types used throughout the codebase.
- `basics` hold basic types such as MicroAlgos, account data, and
addresses.
- `account` defines accounts, including "root" accounts (which can
spend money) and "participation" accounts (which can participate in
the agreement protocol).
- `transactions` define transactions that accounts can issue against
the Algorand state. These include standard payments and also
participation key registration transactions.
- `bookkeeping` defines blocks, which are batches of transactions
atomically committed to Algorand.
- `pools` implement the transaction pool. The transaction pool holds
transactions seen by a node in memory before they are proposed in a
block.
- `committee` implements the credentials that authenticate a
participating account's membership in the agreement protocol.
- `ledger` ([README](ledger/README.md)) contains the Algorand Ledger state
machine, which holds the sequence of blocks. The Ledger executes the state
transitions that result from applying these blocks. It answers queries on
blocks (e.g., what transactions were in the last committed block?) and on
accounts (e.g., what is my balance?).
- `protocol` declares constants used to identify protocol versions, tags for
routing network messages, and prefixes for domain separation of
cryptographic inputs. It also implements the canonical encoder.
- `network` contains the code for participating in a mesh network based on
WebSockets. Maintains connection to some number of peers, (optionally)
accepts connections from peers, sends point to point and broadcast messages,
and receives messages routing them to various handler code
(e.g. agreement/gossip/network.go registers three handlers).
- `rpcs` contains the HTTP RPCs used by `algod` processes to query one
another.
- `agreement` ([README](agreement/README.md)) contains the agreement service,
which implements Algorand's Byzantine Agreement protocol. This protocol
allows participating accounts to quickly confirm blocks in a fork-safe
manner, provided that sufficient account stake is correctly executing the
protocol.
- `node` integrates the components above and handles initialization and
shutdown. It provides queries into these components.
- **crypto**: Contains the cryptographic constructions used for hashing, signatures, and VRFs. It also includes Algorand-specific details about spending keys, protocol keys, one-time-use signing keys, and how they relate to each other.
- **config**: Holds configuration parameters, including those used locally by the node and those that must be agreed upon by the protocol.
- **data**: Defines various types used throughout the codebase.
- **basics**: Holds basic types such as MicroAlgos, account data, and addresses.
- **account**: Defines accounts, including "root" accounts (which can spend money) and "participation" accounts (which can participate in the agreement protocol).
- **transactions**: Defines transactions that accounts can issue against the Algorand state, including standard payments and participation key registration transactions.
- **bookkeeping**: Defines blocks, which are batches of transactions atomically committed to Algorand.
- **pools**: Implements the transaction pool, holding transactions seen by a node in memory before they are proposed in a block.
- **committee**: Implements the credentials that authenticate a participating account's membership in the agreement protocol.
- **ledger** ([README](ledger/README.md)): Contains the Algorand Ledger state machine, which holds the sequence of blocks. The Ledger executes the state transitions resulting from applying these blocks. It answers queries on blocks (e.g., what transactions were in the last committed block?) and on accounts (e.g., what is my balance?).
- **protocol**: Declares constants used to identify protocol versions, tags for routing network messages, and prefixes for domain separation of cryptographic inputs. It also implements the canonical encoder.
- **network**: Contains the code for participating in a mesh network based on WebSockets. It maintains connections to some number of peers, (optionally) accepts connections from peers, sends point-to-point and broadcast messages, and receives messages, routing them to various handler code (e.g., agreement/gossip/network.go registers three handlers).
- **rpcs**: Contains the HTTP RPCs used by `algod` processes to query one another.
- **agreement** ([README](agreement/README.md)): Contains the agreement service, which implements Algorand's Byzantine Agreement protocol. This protocol allows participating accounts to quickly confirm blocks in a fork-safe manner, provided that sufficient account stake is correctly executing the protocol.
- **node**: Integrates the components above and handles initialization and shutdown. It provides queries into these components.

### Daemon

Contains the two daemons which provide Algorand clients with services:
Contains the two daemons that provide Algorand clients with services:

- `daemon/algod` holds the `algod` daemon, which implements a participating
node. `algod` allows a node to participate in the agreement protocol,
submit and confirm transactions, and view the state of the Algorand Ledger.
- `daemon/algod/api` ([README](daemon/algod/api/README.md)) is the REST
interface used for interactions with algod.
- `daemon/kmd` ([README](daemon/kmd/README.md)) holds the `kmd` daemon. This
daemon allows a node to sign transactions. Because `kmd` is separate from
`algod`, `kmd` allows a user to sign transactions on an air-gapped computer.
- **daemon/algod**: Holds the `algod` daemon, which implements a participating node. `algod` allows a node to participate in the agreement protocol, submit and confirm transactions, and view the state of the Algorand Ledger.
- **daemon/algod/api** ([README](daemon/algod/api/README.md)): The REST interface used for interactions with `algod`.
- **daemon/kmd** ([README](daemon/kmd/README.md)): Holds the `kmd` daemon, which allows a node to sign transactions. Since `kmd` is separate from `algod`, it enables a user to sign transactions on an air-gapped computer.

### Interfacing

Allows developers to interface with the Algorand system:
Enables developers to interface with the Algorand system:

- `cmd` holds the primary commands defining entry points into the system.
- `cmd/catchupsrv` ([README](cmd/catchupsrv/README.md)) is a tool to
assist with processing historic blocks on a new node.
- `libgoal` exports a Go interface useful for developers of Algorand clients.
- `tools` ([README](tools/README.md)) various tools and utilities without a better place to go.
- `tools/debug` holds secondary commands which assist developers during debugging.
- `tools/misc` ([README](tools/misc/README.md)) small tools that are sometimes handy in a pinch.
- **cmd**: Contains the primary commands defining entry points into the system.
- **cmd/catchupsrv** ([README](cmd/catchupsrv/README.md)): A tool to assist with processing historic blocks on a new node.
- **libgoal**: Exports a Go interface useful for developers of Algorand clients.
- **tools** ([README](tools/README.md)): Various tools and utilities that don’t have a better place to go.
- **tools/debug**: Holds secondary commands that assist developers during debugging.
- **tools/misc** ([README](tools/misc/README.md)): Small tools that are handy in a pinch.

### Deployment
Help Algorand developers deploy networks of their own:

- `nodecontrol`
- `docker`
- `commandandcontrol` ([README](test/commandandcontrol/README.md)) is a tool to
automate a network of algod instances.
- `components`
- `netdeploy`
Helps Algorand developers deploy networks of their own:

- **nodecontrol**
- **docker**
- **commandandcontrol** ([README](test/commandandcontrol/README.md)): A tool to automate a network of `algod` instances.
- **components**
- **netdeploy**

### Utilities

Provides utilities for the various components:

- `logging` is a wrapper around `logrus`.
- `util` contains a variety of utilities, including a codec, a SQLite wrapper,
a goroutine pool, a timer interface, node metrics, and more.
- **logging**: A wrapper around `logrus`.
- **util**: Contains a variety of utilities, including a codec, a SQLite wrapper, a goroutine pool, a timer interface, node metrics, and more.

### Test
`test` ([README](test/README.md)) contains end-to-end tests and utilities for the above components.

- **test** ([README](test/README.md)): Contains end-to-end tests and utilities for the above components.

## License

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](COPYING)

Please see the [COPYING_FAQ](COPYING_FAQ) for details about how to apply our license.
Please see the [COPYING_FAQ](COPYING_FAQ) for details on how to apply our license.

Copyright (C) 2019-2024, Algorand Inc.

[developer site url]: https://developer.algorand.org/
Loading