Hello, Linera
In this section, you will learn how to initialize a developer wallet, interact with the current Testnet, run a local development network, then compile and deploy your first application from scratch.
By the end of this section, you will have a microchain on the Testnet and/or on your local network, and a working application that can be queried using GraphQL.
Creating a wallet on the latest Testnet
To interact with the latest Testnet, you will need a developer wallet, a new microchain, and some tokens. These can be all obtained at once by querying the Testnet's faucet service as follows:
linera wallet init --with-new-chain --faucet https://faucet.testnet-conway.linera.net
If you obtain an error message instead, make sure to use a Linera toolchain compatible with the current Testnet.
A Linera Testnet is a deployment of the Linera protocol used for testing. A deployment
consists of a number of validators, each of which runs
a frontend service (aka. linera-proxy
), a number of workers (aka. linera-server
), and
a shared database (by default linera-storage-service
).
Using a local test network
Another option is to start your own local development network. To do so, run the following command:
linera net up --with-faucet --faucet-port 8080
This will start a validator with the default number of shards and start a faucet.
Now, we're ready to create a developer wallet by running the following command in a separate shell:
linera wallet init --with-new-chain --faucet http://localhost:8080
A wallet is valid for the lifetime of its network. Every time a local network is restarted, the wallet needs to be removed and created again.
Working with several developer wallets and several networks
By default, the linera
command looks for wallet files located in a
configuration path determined by your operating system. If you prefer to choose
the location of your wallet files, you may optionally set the variables
LINERA_WALLET
and LINERA_STORAGE
as follows:
DIR=$HOME/my_directory
mkdir -p $DIR
export LINERA_WALLET="$DIR/wallet.json"
export LINERA_STORAGE="rocksdb:$DIR/linera.db"
Choosing such a directory can be useful to work with several networks because a wallet is always specific to the network where it was created.
We refer to the wallets created by the linera
CLI as "developer wallets" because
they are operated from a developer tool and merely meant for testing and development.
Production-grade user wallets are generally operated by a browser extension, a mobile application, or a hardware device.
Interacting with the Linera network
To check that the network is working, you can synchronize your chain with the rest of the network and display the chain balance as follows:
linera sync
linera query-balance
You should see an output number, e.g. 10
.
Building an example application
Applications running on Linera are Wasm bytecode. Each validator and client has a built-in Wasm virtual machine (VM) which can execute bytecode.
Let's build the counter
application from the examples/
subdirectory of the
Linera testnet
branch:
cd examples/counter && cargo build --release --target wasm32-unknown-unknown
Publishing your application
You can publish the bytecode and create an application using it on your local
network using the linera
client's publish-and-create
command and provide:
- The location of the contract bytecode
- The location of the service bytecode
- The JSON encoded initialization arguments
linera publish-and-create \
../target/wasm32-unknown-unknown/release/counter_{contract,service}.wasm \
--json-argument "42"
Congratulations! You've published your first application on Linera!
Querying your application
Now let's query your application to get the current counter value. To do that, we need to use the client running in service mode. This will expose a bunch of APIs locally which we can use to interact with applications on the network.
linera service --port 8080
Navigate to http://localhost:8080
in your browser to access GraphiQL, the
GraphQL IDE. We'll look at this in more detail in a
later section; for now, list
the applications deployed on your default chain by running:
query {
applications(chainId: "...") {
id
description
link
}
}
where ...
are replaced by the chain ID shown by linera wallet show
.
Since we've only deployed one application, the results returned have a single entry.
At the bottom of the returned JSON there is a field link
. To interact with
your application copy and paste the link into a new browser tab.
Finally, to query the counter value, run:
query {
value
}
This will return a value of 42
, which is the initialization argument we
specified when deploying our application.