$completium-cli
is a command line interface to interact (originate, call, ...) with Archetype smart contracts on the Tezos blockchain.
The CLI is distributed as a npm package. Install it with the following command:
npm i @completium/completium-cli -g
Once installed, run the init
command:
completium-cli init
The list of available commands is displayed with:
completium-cli help
The Tezos blockchain provides several networks:
- a main network which is the real operating network where real cryptocurrency are exchanged
- several test networks:
- one in the same version (to test current network)
- one(s) in the future main net version(s) (to test/prepare future version of smart contracts)
- optionally several in older versions
Each version of the blockchain is given a name (..., Carthage, Edo, Florence, ...).
An endpoint is an entry node to the network. You interact with the blockchain through an endpoint. You need to specify the endpoint's URL when interacting with the blockchain.
$completium-cli
offers a convenient network management system to register, show and switch networks.
Display the endpoint completium is currently using:
completium-cli show endpoint
For example:
$ completium-cli show endpoint
Current network: granada
Current endpoint: https://testnet-tezos.giganode.io
Select the current endpoint with the following command:
completium-cli switch endpoint
$completium-cli
comes with a set of pre-configured endpoints:
$ completium-cli switch endpoint
Current network: edo
Current endpoint: https://edonet-tezos.giganode.io
? Switch endpoint …
❯ main https://mainnet-tezos.giganode.io
florence https://florence-tezos.giganode.io
granada https://granada-tezos.giganode.io
completium-cli add endpoint (main|florence|granada|hangzhou) <ENDPOINT_URL>
completium-cli remove endpoint <ENDPOINT_URL>
Interacting with a contract requires a Tezos account to sign the transactions. An account is identified by an account address starting by tz1
, like for example tz1MZrh8CvYkp7BfLQMcm6mg5FvL5HRZfACw
.
$completium-cli
provides a convenient account management system to register, list and switch account. Each account is associated with an alias.
When working with the test network, you need fake currencies to interact and test the contracts. There exists a faucet from which you can download a faucet file to generate a test account from.
completium-cli import faucet <FAUCET_FILE> as <ACCOUNT_ALIAS>
completium-cli import privatekey <PRIVATE_KEY> as <ACCOUNT_ALIAS>
The following command displays the account $completium-cli
is currently using:
completium-cli show account
completium-cli switch account
completium-cli set account <ACCOUNT_ALIAS>
The following command transfers tez from one account to another:
completium-cli transfer <AMOUNT>(tz|utz) from <ACCOUNT_ALIAS> to <ACCOUNT_ALIAS|ACCOUNT_ADDRESS>
For example:
$ completium-cli transfer 5.2tz from bob to alice
completium-cli remove account <ACCOUNT_ALIAS>
deploy
is the command to originate an archetype contract (with file extension .arl
), and originate
is the command to originate a michelson contract (with file extension .tz
).
$ completium-cli (deploy <FILE.arl> | originate <FILE.tz>) \
[--as <ACCOUNT_ALIAS>] \
[--named <CONTRACT_ALIAS>] \
[--parameters <PARAM> ] \
[--amount <AMOUNT>(tz|utz)] \
[--metadata-storage <PATH_TO_JSON> | --metadata-uri <VALUE_URI>]
[--init <MICHELSON_DATA>]
[--test-mode]
[--force]
Command | Description |
---|---|
--as |
Deploys with specified account. Default account is the one returned by command completium-cli show account . |
--name |
Names deployed contract with specified logical name. Logical name is used to refer to contract when calling or displaying contract. |
--parameters |
Specifies archetype parameter values (only with archetype contract) |
--amount |
Amount of XTZ to sent when deploying contract. |
--metadata-storage |
Adds metadata to contract from json file (only with archetype contract). |
--metadata-uri |
Adds metadata to contract from uri (only with archetype contract). |
--init |
Overwrites contract initial storage with Michelson value. |
--test-mode |
Generates entrypoint _set_now to set now value (only with archetype contract, to be used only on testnet) |
--force |
Does not prompt for parameter validation. |
For example:
$ completium-cli deploy mycontract.arl --amount 15.5tz
This creates a contract alias mycontract
.
The following archetype contract requires one parameter fee
when deployed:
archetype payment(fee : tez)
variable amount : tez = 150tz
entry pay(seller : address) {
transfer (amount - fee) to seller
}
The command to deploy:
$ completium-cli deploy payment.arl --parameters '{ "fee" : "5tz" }'
One way to set metadata is to provide a json file as the --metadata-storage
argument.
For example the following metadata file:
$ cat fa12_metadata.json
{
"symbol": "MTK",
"name": "MyToken",
"decimals": "1",
"description": "description of MyToken",
"thumbnailUri": "https://completium.com/img/logo_completium_128.png"
}
Then the command to deploy the FA 1.2 contract:
$ completium-cli deploy fa12.arl --metadata-storage fa12_metadata.json
It is possible to show data related to a contract alias:
$ completium-cli show contract <CONTRACT_ALIAS>
For example:
$ completium-cli show contract demo
Name: demo
Network: edo
Address: KT1CQmaCLLdEQ3X9PmxoqEAy3Xusvs1J5wW1
Source: /home/dev/.completium/sources/demo.arl
Language: archetype
Version: 1.2.2
Url: https://better-call.dev/edo2net/KT1CQmaCLLdEQ3X9PmxoqEAy3Xusvs1J5wW1
The following command lists all contracts managed by $completium-cli
:
completium-cli show contracts
It is possible to show the contract source with:
$ completium-cli show source <CONTRACT_ALIAS>
completium-cli show entries <CONTRACT_ADDRESS|CONTRACT_ALIAS>
The command also works with a remote contract address:
completium-cli show entries KT1EFgRdrT4r6QLx2riZiPNHjo7gcQM8n7f7
%confirm (_ : unit)
%submit (%ckey : address, %pscore : int)
%decide (_ : unit)
It is possible to show contract's storage:
$ completium-cli show storage <CONTRACT_ALIAS|CONTRACT_ADDRESS>
or in json format:
$ completium-cli show storage <CONTRACT_ALIAS|CONTRACT_ADDRESS> --json
For example:
$ cat simple.arl
archetype simple
variable v : nat = 0
entry setvalue(p : nat) { v := p }
$ completium-cli deploy simple.arl
? simple already exists, overwrite it? Yes
Originate settings:
network : granada
contract : simple
by : admin
send : 0 ꜩ
storage : 0
total cost : 0.082488 ꜩ
? Confirm settings Yes
Forging operation...
Waiting for confirmation of origination for KT1WVrMD4RWVEkW9gWqH4ntEMNBckG7Lucm8 ...
Origination completed for KT1WVrMD4RWVEkW9gWqH4ntEMNBckG7Lucm8 named simple.
https://better-call.dev/granadanet/KT1WVrMD4RWVEkW9gWqH4ntEMNBckG7Lucm8
$ completium-cli call simple --arg '{ "p" : 2 }'
Call settings:
network : granada
contract : simple_nat
by : admin
send : 0 ꜩ
entrypoint : default
argument : 2
total cost : 0.000532 ꜩ
? Confirm settings Yes
Forging operation...
Waiting for ooGRwqf9GKYsvvggiyqYEF1xRqa9gnXcQDvJJjDt73M1yTrmyAV to be confirmed...
Operation injected: https://granada.tzstats.com/ooGRwqf9GKYsvvggiyqYEF1xRqa9gnXcQDvJJjDt73M1yTrmyAV
$ completium-cli show storage simple
2
$ completium-cli sjow storage simple --json
{ "int" : 2 }
$ completium-cli call <CONTRACT_ADDRESS|CONTRACT_ALIAS> \
[--as <ACCOUNT_ALIAS>] \
[--entry <ENTRYPOINT>] \
[--arg <ARG>] \
[--arg-michelson <MICHELSON_ARG>] \
[--amount <AMOUNT>(tz|utz)] \
[--force]
Command | Description |
---|---|
--as |
Deploys with specified account. Default account is the one returned by command completium-cli show account . |
--entry |
Name of the entrypoint to call. Must be omitted if the contract has only one entrypoint. |
--arg |
Specifies entrypoints parameter values (see example below). |
--arg-michelson |
Specifies entrypoints parameter values in Michelson format. |
--amount |
Amount of XTZ to sent when calling contract. |
--force |
Does not prompt for parameter validation. |
For example, if mycontract.arl
defines a (non-unique) entry point payback
:
entry payback (i : int, n : nat) {
// ...
}
The command to call the entry is:
$ completium-cli call mycontract --entry payback --arg '{ "i" : -4, "n" : 5 }'
This section presents examples of parameter and argument values to pass to deploy --param
and call --arg
commands.
Archetype type | Michelson type | Value examples |
---|---|---|
nat |
nat |
5 |
int |
int |
5 , -10
|
string |
string |
"hello" |
date |
timestamp |
"1629965551" , "2022-01-01T12:00:00Z"
|
bool |
bool |
true , false
|
duration |
int |
-965551 |
address |
address |
"tz1..." |
bytes |
bytes |
"10abff" |
rational |
pair int nat |
[-5, 2] |
tez |
mutez |
5000000 , "5tz" , "5000000utz"
|
int * string |
pair int string |
[-5, "hello"] |
option<int> |
option int |
null (for none ), 1 (for some(1) ) |
or<int, string> |
or int string |
{ "kind" : "right", "value" : "hello" } |
list<string> |
list string |
["world", "hello"] |
set<string> |
set string |
["hello", "world"] (mind order) |
map<nat, string> |
map nat string |
[{ "key" : 0, "value" : "value for 0" }, { "key" : 1, "value" : "value for 1" }] (mind order) |
asset myasset { id : nat, value : string } |
map nat string |
[{ "key" : 0, "value" : "value for 0" }, { "key" : 1, "value" : "value for 1" }] (mind order) |
The javascript version of the contract is required when a DApp is originating the contract using Taquito.
The command to generate the javascript version is:
completium-cli generate javascript <FILE.arl|CONTRACT_ALIAS>
For example:
$ completium-cli generate javascript mycontract.arl > mycontract.js
The generated mycontract.js
file exports:
- the Micheline/Json
code
of the contract - the
getStorage
method to build the initial storage
See here an example of how to use in a DApp.
The whyml version of the contract is required to formally verify the contract with Why3.
The command to generate the whyml version is:
completium-cli generate whyml <FILE.arl|CONTRACT_ALIAS>
For example:
$ completium-cli generate whyml mycontract.arl > mycontract.mlw
The generated mycontract.mlw
file defines 2 modules:
-
Mycontract_storage
that defines the storage -
Mycontract
that defines entrypoints