Repository: linera-io/linera-protocol

Stars: 32137

README.md Copy Chapter

<img src="https://github.com/linera-io/linera-protocol/assets/1105398/fe08c941-93af-4114-bb83-bcc0eaec95f9" width="250" height="85" />


<!--  -->

Linera is a decentralized blockchain infrastructure designed for highly scalable,
secure, low-latency Web3 applications.

Documentation Copy Chapter

Visit our developer page and read our
whitepaper to learn more about the Linera protocol.

Repository Structure Copy Chapter

The main crates and directories of this repository can be summarized as follows: (listed
from low to high levels in the dependency graph)

* linera-base Base
definitions, including cryptography.

* linera-version
A library to manage version info in binaries and services.

* linera-views A
library mapping complex data structures onto a key-value store. The corresponding
procedural macros are implemented in linera-views-derive.

* linera-execution
Persistent data and the corresponding logic for runtime and execution of Linera
applications.

* linera-chain
Persistent data and the corresponding logic for chains of blocks, certificates, and
cross-chain messaging.

* linera-storage
Defines the storage abstractions for the protocol on top of linera-chain.

* linera-core The
core Linera protocol, including client and server logic, node synchronization, etc.

* linera-rpc
Defines the data-type for RPC messages (currently all client &#x2194; proxy &#x2194;
chain &#x2194; chain interactions), and track the corresponding data schemas.

* linera-client
Library for writing Linera clients. Used for the command-line
client and the node service in linera-service, as well as the Web
client in linera-web.

* linera-service
Executable for clients (aka CLI wallets), proxy (aka validator frontend) and servers.

* linera-sdk The
library to develop Linera applications written in Rust for the Wasm virtual machine. The
corresponding procedural macros are implemented in linera-sdk-derive.

* examples Examples of Linera applications written in Rust.

Prerequisites Copy Chapter

See INSTALL.md for software requirements to develop in this repo.

Quickstart with the Linera CLI tool Copy Chapter

The following commands set up a local test network and run some transfers between the
microchains owned by a single wallet.

Make sure to compile the Linera binaries and add them in the $PATH.

cargo build -p linera-storage-service -p linera-service --bins

export PATH="$PWD/target/debug:$PATH"
Import the optional helper function linera_spawn.

source /dev/stdin <<<"$(linera net helper 2>/dev/null)"
Run a local test network with the default parameters and a number of microchains

owned by the default wallet. This also defines LINERA_TMP_DIR.

linera_spawn \
linera net up --with-faucet --faucet-port 8080
Remember the URL of the faucet.

FAUCET_URL=http://localhost:8080
If you're using a testnet, start here and run this instead:

  LINERA_TMP_DIR=$(mktemp -d)

  FAUCET_URL=https://faucet.testnet-XXX.linera.net  # for some value XXX

Enable logs for user applications:

export LINERA_APPLICATION_LOGS=true

Set the path of the future wallet:

export LINERA_WALLET="$LINERA_TMP_DIR/wallet.json"
export LINERA_KEYSTORE="$LINERA_TMP_DIR/keystore.json"
export LINERA_STORAGE="rocksdb:$LINERA_TMP_DIR/client.db"
Initialize a new user wallet.

linera wallet init --faucet $FAUCET_URL
Request chains.

INFO1=($(linera wallet request-chain --faucet $FAUCET_URL))
INFO2=($(linera wallet request-chain --faucet $FAUCET_URL))
CHAIN1="${INFO1[0]}"
ACCOUNT1="${INFO1[1]}"
CHAIN2="${INFO2[0]}"
ACCOUNT2="${INFO2[1]}"
Show the different chains tracked by the wallet.

linera wallet show
Query the chain balance of some of the chains.

linera query-balance "$CHAIN1"
linera query-balance "$CHAIN2"
Transfer 10 units then 5 back.

linera transfer 10 --from "$CHAIN1" --to "$CHAIN2"
linera transfer 5 --from "$CHAIN2" --to "$CHAIN1"
Query balances again.

linera query-balance "$CHAIN1"
linera query-balance "$CHAIN2"
Now let's fund the user balances.

linera transfer 5 --from "$CHAIN1" --to "$ACCOUNT1@$CHAIN1"
linera transfer 2 --from "$ACCOUNT1@$CHAIN1" --to "$ACCOUNT2@$CHAIN2"
Query user balances again.

linera query-balance "$ACCOUNT1@$CHAIN1"
linera query-balance "$ACCOUNT2@$CHAIN2"

More complex examples may be found in our developer manual as well
as the example applications in this repository.

Contributing Copy Chapter

We welcome contributions from the community! If you'd like to contribute to the Linera protocol:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

For detailed guidelines, see our contribution guide.