Command Line
Install the @accordproject/ergo-cli npm package to access the Ergo command line interface (CLI). After installation you can use the ergo command and its sub-commands as described below.
To install the Ergo CLI:
npm install -g @accordproject/ergo-cli
This will install ergo, to compile and run contracts locally on your machine, and ergotop, which is a read-eval-print-loop utility to write Ergo interactively.
Ergo
Usage
ergo <command>
Commands:
ergo trigger send a request to the contract
ergo invoke invoke a clause of the contract
ergo initialize initialize the state for a contract
ergo compile compile a contract
Options:
--help Show help [boolean]
--version Show version number [boolean]
--verbose, -v [default: false]
ergo trigger
ergo trigger allows you to send a request to the contract.
Usage: ergo trigger --data [file] --state [file] --request [file] [cto files] [ergo files]
Options:
--help Show help [boolean]
--version Show version number [boolean]
--verbose, -v [default: false]
--data path to the contract data [required]
--state path to the state data [string] [default: null]
--currentTime set current time [string] [default: null]
--utcOffset set UTC offset [number] [default: null]
--request path to the request data [array] [required]
--template path to the template directory [string] [default: null]
--warnings print warnings [boolean] [default: false]
Example
For example, using the trigger command for the Volume Discount example in the Ergo Directory:
ergo trigger --template ./tests/volumediscount --data ./tests/volumediscount/data.json --request ./tests/volumediscount/request.json --state ./tests/volumediscount/state.json
returns:
{
"clause": "orgXaccordprojectXvolumediscountXVolumeDiscount",
"request": {
"$class": "org.accordproject.volumediscount.VolumeDiscountRequest",
"netAnnualChargeVolume": 10.4
},
"response": {
"$class": "org.accordproject.volumediscount.VolumeDiscountResponse",
"discountRate": 2.8,
"$timestamp": "2021-06-17T09:36:53.847-04:00"
},
"state": {
"$class": "org.accordproject.runtime.State",
"$identifier": "7c19d1e3-1f70-4b30-8c3d-086dc45b1dd1"
},
"emit": []
}
As the request was sent for an annual charge volume of 10.4, which falls into the third discount rate category (as specified in the data.json file), the response returns with a discount rate of 2.8%.
ergo invoke
ergo invoke allows you to invoke a specific clause of the contract. The main difference between ergo invoke and ergo trigger is that ergo invoke sends data to a specific clause, whereas ergo trigger lets the contract choose which clause to invoke. This is why --clauseName (the name of the contract you want to execute) is a required field for ergo invoke.
You need to pass the CTO and Ergo files (--template), the name of the contract that you want to execute (--clauseName), and JSON files for: the contract data (--data), the contract parameters (--params), the current state of the contract (--state), and the request.
If contract invocation is successful, ergorun will print out the response, the new contract state and any emitted events.
Usage: ergo invoke --data [file] --state [file] --params [file] [cto files] [ergo files]
Options:
--help Show help [boolean]
--version Show version number [boolean]
--verbose, -v [default: false]
--clauseName the name of the clause to invoke [required]
--data path to the contract data [required]
--state path to the state data [string] [required]
--currentTime set current time [string] [default: null]
--utcOffset set UTC offset [number] [default: null]
--params path to the parameters [string] [required] [default: {}]
--template path to the template directory [string] [default: null]
--warnings print warnings [boolean] [default: false]
Example
For example, using the invoke command for the Volume Discount example in the Ergo Directory:
ergo invoke --template ./tests/volumediscount --clauseName volumediscount --data ./tests/volumediscount/data.json --params ./tests/volumediscount/params.json --state ./tests/volumediscount/state.json
returns:
{
"clause": "orgXaccordprojectXvolumediscountXVolumeDiscount",
"params": {
"request": {
"$class": "org.accordproject.volumediscount.VolumeDiscountRequest",
"netAnnualChargeVolume": 10.4
}
},
"response": {
"$class": "org.accordproject.volumediscount.VolumeDiscountResponse",
"discountRate": 2.8,
"$timestamp": "2021-06-17T09:38:03.189-04:00"
},
"state": {
"$class": "org.accordproject.runtime.State",
"$identifier": "b757ad1f-e011-4fda-9b37-e7157512300f"
},
"emit": []
}
Although this looks very similar to what ergo trigger returns, it is important to note that --clauseName volumediscount was specifically invoked.
ergo initialize
ergo initialize allows you to obtain the initial state of the contract. This is the state of the contract without requests or responses.
Usage: ergo intialize --data [file] --params [file] [cto files] [ergo files]
Options:
--help Show help [boolean]
--version Show version number [boolean]
--verbose, -v [default: false]
--data path to the contract data [required]
--currentTime set current time [string] [default: null]
--utcOffset set UTC offset [number] [default: null]
--params path to the parameters [string] [default: null]
--template path to the template directory [string] [default: null]
--warnings print warnings [boolean] [default: false]
Example
For example, using the initialize command for the Volume Discount example in the Ergo Directory:
ergo initialize --template ./tests/volumediscount --data ./tests/volumediscount/data.json
returns:
{
"clause": "orgXaccordprojectXvolumediscountXVolumeDiscount",
"params": {
},
"response": null,
"state": {
"$class": "org.accordproject.runtime.State",
"$identifier": "af4f0f49-2658-4465-87f4-780e7d2e38a8"
},
"emit": []
}
ergo compile
ergo compile takes your input models (.cto files) and input contracts (.ergo files) and allows you to compile a contract into a target platform. By default, Ergo compiles to JavaScript (ES6 compliant) for execution.
Usage: ergo compile --target [lang] --link --monitor --warnings [cto files] [ergo files]
Options:
--help Show help [boolean]
--version Show version number [boolean]
--verbose, -v [default: false]
--target Target platform (available: es5,es6,cicero,java)
[string] [default: "es6"]
--link Link the Ergo runtime with the target code (es5,es6,cicero
only) [boolean] [default: false]
--monitor Produce compilation time information [boolean] [default: false]
--warnings print warnings [boolean] [default: false]
Example
For example, using the compile command on the Volume Discount example in the Ergo Directory:
ergo compile ./tests/volumediscount/model/model.cto ./tests/volumediscount/logic/logic.ergo
returns:
Compiling Ergo './tests/volumediscount/logic/logic.ergo' -- './tests/volumediscount/logic/logic.js'
Which means a new logic.js file is located in the ./tests/volumediscount/logic directory.
To compile the contract to Javascript and link the Ergo runtime for execution:
ergo compile ./tests/volumediscount/model/model.cto ./tests/volumediscount/logic/logic.ergo --link
returns:
Compiling Ergo './tests/volumediscount/logic/logic.ergo' -- './tests/volumediscount/logic/logic.js'