Getting started
This section is aimed at newcomers to Ligo and Tezos smart-contracts. In this tutorial, we will go through the following step :
- Setting up the development environment,
- Writing a simple contract in Cameligo
- Testing the contract
- Deploying the contract to Tezos
Setting up the development environment.
At the present moment, we recommend the user to develop on a UNIX system, GNU/Linux or MacOSX as the windows native binary is still in preparation. You can still use Ligo on windows through our docker image More on installation and editor support
Alternatively, you can decide to use our webide. This can be useful for testing or for small project. However, it doesn't scale well for bigger size project as you won't be able to spread your project across multiple files and use your own libraries.
Install ligo
Static Linux binary
The ligo
executable is statically linked. It should run on most modern Linux distributions.
You can get the rolling release here, make it executable, and you are done!
For a specific version, you can visit our release page.
Optionally, you can put it somewhere in your PATH
for easy access:
MacOS
Try our tap,
Debian Linux package installation
A .deb
package containing the static ligo
executable is also available.
First, download the package, and then install using:
Dockerised installation
If you've installed 🐳 Docker, you can run the latest LIGO release :
Linux or OSX:
docker run --rm -v "$PWD":"$PWD" -w "$PWD" ligolang/ligo:For convenience you can alias the above command
alias ligo="docker run --rm -v "$PWD":"$PWD" -w "$PWD" ligolang/ligo:"To make this
alias
persistent across terminal sessions you need to configure your shell. Here is a good link with the steps on how to do that.
Windows:
docker run --rm -v "%CD%":/cd -w /cd ligolang/ligo:`For convenience you can alias the above command
doskey ligo=docker run --rm -v "%CD%":/cd -w /cd ligolang/ligo: $*To make the alias persistent across terminal sessions you need to add the
doskey
to the Windows Registry. Follow this stackoverflow answer for the steps on how to do that.
Or if you want the development version, replace the version above with next
.
Or run one of the older versions found on DockerHub.
Setting up the editor
You can see the updated list of supported editor here
In this tutorial, we will use vs-code.
For vs-code, simply go to the extension menu in the left bar (Ctrl + Shift + X) and search for the
ligo-vscode
extension and install it.For emacs, follow the instruction here
For vim, follow the instruction here
Once, you've done it, you are ready to make your first smart-contract
Install the Tezos tools
To deploy your smart-contract on the network and to test it, you will need to use a Tezos client.
On GNU/Linux, the simplest way to get octez-client is through opam using
opam install tezos
. alternatives are available hereOn MacOsX, the software is distributed through a brew formula with
brew install tezos
.
Building a smart-contract.
From a template
Rather you're curious to see how to make NFT or randomness in LIGO, or you want to have an example for a more complex architecture, you can have a look in this collection of templates made by the LIGO team.
From scratch
In this section and the following one we will use a simple smart-contract that is present as example on our webide. We will cover the LIGO language and smart-contract development in the following tutorials.
First, create a ligo_tutorial
folder on your computer. Then download and put the contract in this folder. It is available in CameLIGO and JsLIGO
Open your editor in the folder and the file starting.jsligo
in the editor. You should have this code
Now we are going to compile the contract, open a terminal in the folder. (or the vs-code built-in terminal with Ctrl+shift+²) and run the following command:
The compile contract
takes a filename, the file you want to
compile. The -m
parameter indicates the namespace or module
corresponding to the contract to compile inside the file. The -o
parameter indicates to store the result in starting.tz
instead of
outputting it in the terminal.
LIGO will aggregate all functions marked with @entry
inside the
module/namespace and build a contract function from them that
dispatches according to the parameter passed. This function is the
default contract function compiled, but if there are no functions
marked with @entry
, LIGO will look for an entrypoint with name
main
. Different entrypoints can be selected using -e
.
Now, you should have a Michelson contract starting.tz
in the folder
ready to be deploy. But before that, we want to test it to be sure
that it behaves as expected, because once publish, it cannot be
modified.
Testing the contract
As we can never underline enough the importance of tests in the context of smart-contract. We will now test our contract three times on different levels :
Test the code from the command line
Using the interpret
command, one can run LIGO code in the context of an init file. For instance
will run <code>
after evaluating everything in the contract file. This is useful to test arbitrary functions and variables in your code.
For instance, to test the add
function you can run
which should return 42
.
Running several of this command will cover the complete code.
To run the contract as if it was called on the blockchain, the command
dry-run
can be used. It takes the contract, the parameter and the
initial storage, and we also need to pass the namespace/module using -m
:
which will return (LIST_EMPTY(), 42)
.
Combine several of those command to fully test the contract use-cases.
Test the code with LIGO test framework.
In LIGO, you are able to write tests directly in the source file, using the Test
module.
Add the following line at the end of starting.jsligo
which execute the same test as the previous section.
Now simply run the command
The command will run every function starting with test
and return their values.
More on the syntax for the test framework here and more on how to write and test namespace/module contracts here.
Testing the Michelson contract
The LIGO compiler is made so the produced Michelson program types and correspond to the initial LIGO program. However until we have tools for formal verification, we advise testing that the Michelson code will behave as the LIGO one. For this purpose, you should also write a test for the Michelson code.
There is different methods for testing Michelson code. In this tutorial we will focus on octez-client
mockup. More information here
This method consist in running a "mockup" Tezos chain on our computer, push the contract on the chain and send transaction to the chain to test the contract behaviour.
First, create a temporary folder for the mockup chain by running
Now start the node by running
This will run the node using the Lima
protocol and return a few address, aliased from bootstrap1 to 5. For other version, check
octez-client list mockup protocols
You can now originate the contract to the mock net with :
you should see a lot of information on the command line and the information New contract ... originated
You can now start testing the contract.
To check its storage run :
You should see a 10
in your terminal
We are now ready to send a transaction to our contract. We want to send a transaction with parameter "Increment (32)" but the parameter is written is LIGO. For that, it must first be converted to a Michelson parameter. Which is done by running :
Which gives you the result (Left (Right 32))
Now we can send our transaction with the command
The network will again send back many information including the updated storage which should now be equal to 42.
This conclude our section about testing. As an exercise, you can write the test for the other entrypoint (decrease and reset). Once you are sure that the contract work correctly for all the use cases, you can move on to the next section
Publishing the contract
For deploying the contract on Tezos, we will use the octez-client
interface like we did on the previous section.
First, you will need an account address. You can get one using any wallet listed here.
Once you have your first account configured, go to a faucet, select the ghostnet
testnet and claim XTZ
tokens. clikc on the faucet and you will receive some tokens to play with.
Then we are going to point the Tezos client to a Ghostnet testnet node
This is the testnet, which is a separate network from Tezos, use for testing.
Export the mnemonic from your wallet (almost every wallet does it, look on settings or read wallet documentation to see how to do it), then import your account locally. Type on the terminal
Paste the mnemonic when prompt appears
You are now ready to originate your contract with your user. On your wallet, copy your public hash key address tz1...
or tz2...
and replace the placeholder <my_tz_address...>
on the command you need to run :
Again, you will receive several messages from the node and you should get the confirmation that the contract has been published.
You can search your contract on the network using the portal Better call dev
You can know call your contract with
If you do so, you will see several information on the operation, including the new contract storage.
This conclude this part of our tutorial. You should now be able to compile, test, publish and call a contract. Now you can go to the tacos shop tutorial to know more about programming with LIGO or you can start developing your own contract using the LIGO syntax you are more familiar with.