1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
| rel/stable <br> [](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fstable) | rel/beta <br> [](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fbeta) | rel/nightly <br> [](https://circleci.com/gh/algorand/go-algorand/tree/rel%2Fnightly) |
| --- | --- | --- |
# go-algorand
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.
## 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/).
### 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.
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:
```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.
#### build
```bash
make install
```
#### test
```bash
# unit tests
make test
# integration tests
make integration
```
#### style and checks
```bash
make fmt
make lint
make fix
make vet
```
or alternatively
```bash
make sanity
```
### 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
`${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.
#### 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/`.
## Contributing
Please refer to our [CONTRIBUTING](CONTRIBUTING.md) document.
## Project Layout
`go-algorand` is split into various subsystems containing various 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.
### Daemon
Contains the two daemons which 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.
### Interfacing
Allows 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.
### 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`
### 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.
### Test
`test` ([README](test/README.md)) contains end-to-end tests and utilities for the above components.
## License
[](COPYING)
Please see the [COPYING_FAQ](COPYING_FAQ) for details about how to apply our license.
Copyright (C) 2019-2023, Algorand Inc.
[developer site url]: https://developer.algorand.org/
|
