æternity Documentation Hub
Aeternity.comAeternity GitHub
  • æternity Hub
  • Developer Documentation
  • Aeternity Expansions
    • PULL_REQUEST_TEMPLATE
    • AEX X
    • AEXS
      • AEX 1
      • aex-10
      • AEX 11 Fungible Token Standard
      • AEX-130: æpps Metadata Format Specification
      • aex-141
      • AEX 2
      • AEX-3
      • AEX-4
      • AEX 5
      • AEX 7
      • AEX 8
      • aex-9
    • .github
      • ISSUE_TEMPLATE
        • aexpansion
  • AeMdw - Aeternity Middleware
    • Changelog
    • docs
      • AE MDW Architecture
      • AeMdw Hyperhain Setup Documentation
      • AeMdw Docker Setup Documentation
  • Æternity <> Ethereum Bridge
    • Changelog
  • aepp-cli-js
    • CHANGELOG
    • Contributor guide
    • reference
    • user-guide
    • .github
      • ISSUE_TEMPLATE
  • Hyperchain Bridge
    • Changelog
  • æternity's JavaScript SDK
    • Installation
      • Changelog
      • Compatibility Table
      • Quick Start
      • Transaction options
      • Development
        • Releases
      • guides
        • The range of possible address length
        • AENS (æternity naming system)
        • Batch Transactions
        • How to build a wallet
        • Connect an æpp to a wallet
        • Contract Events
        • Contracts
        • Error Handling
        • JWT usage
        • Ledger Hardware Wallet
        • Low vs High level API
        • Aeternity snap for MetaMask
        • Oracles
        • PayingForTx (Meta-Transactions)
        • Typed data hashing and signing
        • Usage with TypeScript
        • migration
          • Migration to 10.0.0
          • Migration to 11.0.0
          • Migration to 12.0.0
          • Migration to 13.0.0
          • Migration to 14.0.0
          • Migration to 7.0.0
          • Migration to 9.0.0
      • tutorials
        • vuejs
          • Vue.js HelloWorld
    • Examples
      • How to connect wallet to æpp using æternity's JS SDK
        • Sample æpp for contracts
        • iframe-based wallet
        • WebExtension-based wallet
    • .github
      • ISSUE_TEMPLATE
        • bug_report
        • feature_request
  • AEproject
    • Changelog
    • docs
      • Quick Start
      • AEproject Library
      • Migration from 3.x.x to 4.x.x
      • Migration from 4.x.x to 5.x.x
      • Upcoming Version Support
      • cli
        • Local Environment
        • Project Initialization
        • Unit Testing
    • .github
      • ISSUE_TEMPLATE
        • bug_report
        • feature_request
  • aerepl
    • Changelog
  • aescan
    • Changelog
    • Contributor Covenant Code of Conduct
    • Aescan Contributing Guide
    • LICENSE
    • .github
      • pull_request_template
      • ISSUE_TEMPLATE
        • bug_report
        • feature_request
    • docs
      • BRANCHING_STRATEGY
  • Sophia Support for Visual Studio Code
    • Changelog
  • aesophia
    • Changelog
    • Contributing to Sophia
    • docs
      • aeso_aci
      • aeso_compiler
      • Introduction
      • sophia
      • Contract examples
      • Features
      • Standard library
      • Syntax
  • aesophia_cli
    • Changelog
  • aesophia_http
    • Changelog
  • Æ Studio - Formerly known as 🔥 Fire Editor ! Aeternity's easy to use editor for writing smart contr
    • ideas
  • aeternity
    • .github
      • The Æternity Code of Conduct
      • Contributing to the Aeternity node
      • ISSUE_TEMPLATE
        • bug_report
        • feature_request
    • Welcome to Aeternity node documentation
      • Summary
      • Node API
      • Introduction
      • Build from source
      • Configuration
      • CUDA Miner
      • debian_ubuntu_packaging
      • Docker
      • Fork resistance in Aeternity nodes
      • Garbage Collection
      • Hacking the Aeternity Codebase
      • Hardware Requirements
      • hyperchains
      • Installation
      • Network Monitoring
      • Operation
      • Rebar Quick Guide
      • Stratum
      • Testing
      • Update
      • release-notes
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • About this release
        • next-ceres
          • GH-3706-micro_block_gas_limit_used_gas
          • GH-4009-allow_contract_call_by_name
          • GH-4056-add_raw_data_pointers_to_AENS
          • GH-4080-wildcard_aens_delegation_signature
          • GH3417-tamper_protection_on_ga_meta_tx
          • aega_only_allow_attach_for_fresh_accounts
          • aens_auction_adjustments
          • aens_preclaim_optional
          • deprecate_swagger
          • fate_extensions
        • next
          • GH-3088-db_direct_access-as-default
          • GH-4087_http_endpoint_info_inner_txs
          • GH4157-control-mempool-sync-start
    • Emergency patching of OTP modules
    • rosetta
    • apps
      • aehttp
        • priv
          • rosetta_README
    • data
      • aecore
        • Token migration contract
  • Hyperchains whitepaper
    • Hyperchains: Bridging Security and Scalability Through Periodic Synchronization
    • LICENSE
    • Periodically-Syncing-HyperChains
    • generations
    • Glossary
    • Hyperchain Properties
    • staking
  • æternity protocol
    • æternity naming system
    • Gossip
    • Stratum
    • SYNC
    • Serialization formats
    • State Channels
      • Off-chain
      • On-chain
      • Authentication
      • Channel off-chain state
    • æternity consensus protocol
      • Bitcoin-NG for æternity
      • Coinbase at height
      • consensus
      • Coins locking
    • Smart Contracts
      • The æternity Ethereum virtual machine (AEVM)
      • contract_state_tree
      • Contract Transactions
      • Virtual machines on the æternity blockchain
      • contracts
      • Events
      • fate
      • The Solidity Language
      • sophia
      • sophia_stdlib
    • Generalized accounts
      • Generalized accounts - explained
      • generalized_accounts
    • Oracles
      • Oracle life cycle examples
      • Oracle state tree
      • Oracle transactions
      • oracles
    • Sync
      • P2P messages
      • Mempool/TX-pool synchronization
    • node
      • æternity node API
        • Account management - intended usage
        • Encoding scheme for API identifiers and byte arrays
        • State channel WebSocket API
        • Channels - intended usage
        • Contracts - intended usage
        • Mining - intended usage
        • Naming System - intended usage
        • Oracles - intended usage
        • Spending coins - intended usage
        • examples
          • æternity node channel WebSocket API examples
            • json-rpc
              • sc_ws_basic_open_close
              • sc_ws_basic_open_close_server
              • sc_ws_broken_open_params
              • sc_ws_close_mutual
              • sc_ws_close_solo
              • sc_ws_leave_reconnect
              • sc_ws_leave_reestablish
              • sc_ws_leave_reestablish_responder_stays
              • sc_ws_leave_reestablish_wrong_fsm_id
              • sc_ws_min_depth_is_modifiable
              • sc_ws_min_depth_not_reached_timeout
              • sc_ws_opening_ping_pong
              • sc_ws_reconnect_early
              • sc_ws_slash
              • sc_ws_snapshot_solo
              • sc_ws_timeout_open
              • sc_ws_update_with_meta
              • abort_updates
                • sc_ws_abort_deposit
                • sc_ws_abort_offchain_update
                • sc_ws_abort_settle
                • sc_ws_abort_shutdown
                • sc_ws_abort_slash
                • sc_ws_abort_snapshot_solo
                • sc_ws_abort_withdraw
                • sc_ws_can_not_abort_while_open
              • assume_min_depth
                • sc_ws_basic_open_close
              • both_sign
                • init_per_group
                • conflicts
                  • sc_ws_conflict_deposit_and_offchain_update
                  • sc_ws_conflict_two_deposits
                  • sc_ws_conflict_two_offchain_updates
                  • sc_ws_conflict_two_withdrawals
                  • sc_ws_conflict_withdrawal_and_deposit
                  • sc_ws_conflict_withdrawal_and_offchain_update
              • changeable_fee
                • sc_ws_optional_params_close_solo
                • sc_ws_optional_params_create
                • sc_ws_optional_params_deposit
                • sc_ws_optional_params_settle
                • sc_ws_optional_params_slash
                • sc_ws_optional_params_snapshot
                • sc_ws_optional_params_withdrawal
                • sc_ws_set_fee_close_mutual
                • sc_ws_set_fee_close_solo
                • sc_ws_set_fee_create
                • sc_ws_set_fee_deposit
                • sc_ws_set_fee_settle
                • sc_ws_set_fee_slash
                • sc_ws_set_fee_snapshot
                • sc_ws_set_fee_withdrawal
              • changeable_fee_higher_than_gas_price
                • sc_ws_optional_params_close_solo
                • sc_ws_optional_params_create
                • sc_ws_optional_params_deposit
                • sc_ws_optional_params_settle
                • sc_ws_optional_params_slash
                • sc_ws_optional_params_snapshot
                • sc_ws_optional_params_withdrawal
              • changeable_fee_lower_than_gas_price
                • sc_ws_optional_params_close_solo
                • sc_ws_optional_params_create
                • sc_ws_optional_params_deposit
                • sc_ws_optional_params_settle
                • sc_ws_optional_params_slash
                • sc_ws_optional_params_snapshot
                • sc_ws_optional_params_withdrawal
              • changeable_gas_price
                • sc_ws_optional_params_close_solo
                • sc_ws_optional_params_create
                • sc_ws_optional_params_deposit
                • sc_ws_optional_params_settle
                • sc_ws_optional_params_slash
                • sc_ws_optional_params_snapshot
                • sc_ws_optional_params_withdrawal
              • changeable_nonce
                • sc_ws_optional_params_fail_close_mutual
                • sc_ws_optional_params_fail_close_solo
                • sc_ws_optional_params_fail_create
                • sc_ws_optional_params_fail_deposit
                • sc_ws_optional_params_fail_force_progress
                • sc_ws_optional_params_fail_settle
                • sc_ws_optional_params_fail_slash
                • sc_ws_optional_params_fail_snapshot
                • sc_ws_optional_params_fail_withdrawal
              • continuous
                • init_per_group
                • sc_ws_deposit
                • sc_ws_failed_update
                • sc_ws_generic_messages
                • sc_ws_ping_pong
                • sc_ws_update_conflict
                • sc_ws_withdraw
              • contracts
                • init_per_group
                • sc_ws_basic_contracts
                • sc_ws_environment_contract
                • sc_ws_nameservice_contract
                • sc_ws_oracle_contract
                • sc_ws_remote_call_contract
                • sc_ws_remote_call_contract_refering_onchain_data
                • sc_ws_wrong_call_data
              • force_progress
                • sc_ws_force_progress_based_on_offchain_state
                • sc_ws_force_progress_based_on_onchain_state
              • only_one_signs
                • init_per_group
                • sc_ws_conflict_on_new_offchain
                • sc_ws_conflict_snapshot_and_offchain_update
                • conflicts
                  • sc_ws_conflict_deposit_and_offchain_update
                  • sc_ws_conflict_two_deposits
                  • sc_ws_conflict_two_offchain_updates
                  • sc_ws_conflict_two_withdrawals
                  • sc_ws_conflict_withdrawal_and_deposit
                  • sc_ws_conflict_withdrawal_and_offchain_update
              • reconnect
                • sc_ws_basic_client_reconnect_i
                • sc_ws_basic_client_reconnect_i_w_reestablish
                • sc_ws_basic_client_reconnect_r
              • with_meta
                • init_per_group
                • sc_ws_deposit
                • sc_ws_remote_call_contract
                • sc_ws_withdraw
              • generalized_accounts
                • both
                  • sc_ws_basic_open_close
                • initiator
                  • sc_ws_basic_open_close
                • responder
                  • sc_ws_basic_open_close
  • Superhero Wallet
    • Changelog
    • Contributing & Guidelines
    • docs
      • Deep link URL Schema
    • .github
      • ISSUE_TEMPLATE
        • bug_report
        • feature_request
  • aerepl-web-bridge
    • AereplApi
    • aerepl_components
Powered by GitBook
On this page
  • æREPL --- an interactive shell for Sophia
  • Setup
  • Dependencies
  • Local build
  • Docker/podman image
  • CLI usage
  • Typechecking
  • Working with files
  • In-REPL state
  • Configuration
  • Output format
  • Multiline input
  • Generic server interface
  • Startup
  • Call
  • Cast
  • Functions

Was this helpful?

Export as PDF

aerepl

Previousfeature_requestNextChangelog

Last updated 22 days ago

Was this helpful?

æREPL --- an interactive shell for Sophia

Try Sophia, test your contracts, check "what if", calculate a factorial. Completely offline, independently from remote networks, no dockers required.

If you are not familiar with Sophia, check first.

Setup

Dependencies

Tools:

  • git

  • OTP 25 or 26

  • C++ compiler

Libraries:

Local build

Clone the repo:

git clone https://github.com/aeternity/aerepl.git

Set up the environment:

export ERLANG_ROCKSDB_OPTS="-DWITH_SYSTEM_ROCKSDB=ON -DWITH_LZ4=ON -DWITH_SNAPPY=ON -DWITH_BZ2=ON -DWITH_ZSTD=ON"
export CXXFLAGS="-Wno-error=shadow -Wno-deprecated-copy -Wno-redundant-move -Wno-pessimizing-move"
cd aerepl
make

Launch the REPL

./aerepl

Docker/podman image

For a consistent setup, a docker image can be created:

make docker

Then to start the dockerized REPL:

docker run -i aeternity/aerepl:local

Use make podman for a podman build.

CLI usage

Main functionality of æREPL is to evaluate Sophia expressions:

AESO> 2 + 2
4

Aside from that, values can be assigned to REPL-local variables (pattern matching is supported)

AESO> let x = 2
AESO> let (q, w) = (x + 1, x - 1)
AESO> q
3
AESO> w
1

Functions and types are supported as well

AESO> record point = {x : int, y : int}
AESO> function get_x(p : point) = p.x
AESO> get_x({x = 100, y = 42})
100

NOTE: in-REPL functions cannot use in-REPL variables and other functions yet.

Typechecking

A common query is to ask about the type of an expression. This is done using the:type command:

AESO> :type Oracle.query
(oracle('a, 'b), 'a, int, Chain.ttl, Chain.ttl) => oracle_query('a, 'b)

Working with files

æREPL allows loading files to call their code and deploy contracts defined in them. To load a file, the :load command may be used:

// File: Test.aes
namespace N =
  function f() = 100

contract C =
  entrypoint f() = N.f() + 23
AESO> :load Test.aes
AESO> N.f()
100
AESO> let c = Chain.create() : C
AESO> c.f()
123

If multiple files are loaded, only the most recent one is brought to the scope. To include other loaded files into the working scope, Sophia's include should be used:

AESO> include "List.aes"

Note that :load reloads all listed files and unloads those skipped. Yet another useful command is :reload, which reloads all loaded files, preserving the included scope.

AESO> :load X.aes Y.aes
AESO> Y.y()  // defined in Y.aes
"y"
AESO> X.x()  // defined in X.aes
1:1 Unbound variable: X.x
AESO> include "X.aes"
AESO> X.x()  // Now it works
"x"

:load and :reload clear out the scope, meaning that they will clean

  • User defined variables

  • User defined functions

  • User defined types

  • Includes

  • Deployed contracts

  • In-REPL state

In-REPL state

æREPL maintains its own Sophia state which can be accessed using standard operations put and state, as well as stateful functions. By default, the state is set to () : unit. In order to change it to some other type, :state command should be used:

AESO> :set print_unit true
AESO> state
()
AESO> :state 1000
AESO> state + 1
1001
AESO> put(state / 2)
()
AESO> state
500

Note that :state is parameterized by value, not by type. The value has to have a fully instantiated, non-functional type. Changing the state using the :state commands clears out all user-defined variables and functions --- if that is not desired, put should be used to modify the state if possible.

Configuration

æREPL can be configured interactively using the :set command. The syntax for this command is :set OPTION [ARGS], for example

AESO> :set print_unit true

Currently the supported options are:

Option
Arguments
Description

call_gas

non-neg int

Determines the amount of gas to be supplied to each query.

-------------------------

--------------------

:--------------------------------------------------------------------

call_value

non-neg int

The value, the amount of tokens supplied with the query.

-------------------------

--------------------

:--------------------------------------------------------------------

call_gas_price

non-neg int

The result of Call.gas_price

-------------------------

--------------------

:--------------------------------------------------------------------

call_origin

pubkey

The account to initiate execution of in-REPL code.

Defines Call.origin and initial Call.caller.

-------------------------

--------------------

:--------------------------------------------------------------------

call_contract_creator

pubkey

The result of Contract.creator.

-------------------------

--------------------

:--------------------------------------------------------------------

call_fee

non-neg int

The result of Call.fee.

-------------------------

--------------------

:--------------------------------------------------------------------

call_height

non-neg int

The result of Chain.block_height.

-------------------------

--------------------

:--------------------------------------------------------------------

print_gas

true/false

If true, REPL will print gas used for evaluating each expression.

-------------------------

--------------------

:--------------------------------------------------------------------

print_format

sophia/fate/json

Determines the syntax used to display values.

-------------------------

--------------------

:--------------------------------------------------------------------

print_unit

true/false

Whether to display unit (()).

-------------------------

--------------------

:--------------------------------------------------------------------

print_type

true/false

Whether to display the type after each eval.

-------------------------

--------------------

:--------------------------------------------------------------------

loc_backwards

non-neg int

Number of previous lines to be displayed when using location.

-------------------------

--------------------

:--------------------------------------------------------------------

loc_forwards

non-neg int

Number of further lines to be displayed when using location.

Output format

By default, the REPL shall display values preserving compatibility with Sophia syntax. An exception from that rule are values containing functions which in FATE are represented as pairs of function name and closure. In that case, the output will take a form of "<fun $FUNHASH>" : $TYPE where $TYPE is the type of the function (according to the Sophia code, not FATE bytecode), and$FUNHASH is a hex-encoded shortcut of the original function's name hashed with BLAKE2B (as it is stored in the bytecode). For example

AESO> () => ()
"<fun E3472E14>" : () => unit

If print_format is set to fate, the value shall be displayed as an Erlang term that describes the exact representation of the value in the runtime.

AESO> :set print_format fate
AESO> record r = {x : int, y : int}
AESO> {y = 100, x = 7}
{tuple,{7,100}}
AESO> Some(1)
{variant,[0,1],1,{1}}
AESO> () => ()
{tuple,{<<227,71,46,20>>,{tuple,{}}}}

If set to json, the values will be encoded in JSON format. Information about record fields and datatype constructor names shall not be dropped. Function values are represented as strings in the same manner as in the sophia format.

AESO> :set print_format json
AESO> record r = {x: int, y : int}
AESO> ({x = 3, y = 4}, "STRING")
[
  {
    "x": 3,
    "y": 4
  },
  "STRING"
]

Multiline input

To type in a multiline block of code, surround it with :{ and :}:

AESO> :{
| let x = 123
| x
| :}
123

Generic server interface

If REPL is used as a library for a different tool, its generic server can be used for more structured interface. The server is located insrc/aere_gen_server.erl and implements the standard gen_server Erlang behaviour.

Startup

Use aere_gen_server:start/1 to start up the server. aere_gen_server:start/2 allows to start a server under a custom name. The argument is property list with the following fields:

  • options --- parameter map for the repl configuration. See "Configuration" for more details.

  • accounts :: list(#{pubkey() => integer()}) --- list of initial accounts and their balances

Call

  • quit --- terminates the server

  • skip --- does nothing

  • bump_nonce --- bumps internal REPL nonce (used in naming internal variables)

  • blockchain_state --- returns the chain state for the current session

  • theme --- returns the current display theme

  • {type, string()} --- parses the expression and returns its type in the session context

  • {state, string()} --- parses the expression and evaluates it in the session context. The restult is then assigned to the session's contract store. All locally defined functions, variables and types are pruned.

  • {eval, string()} --- parses the expression and evaluates it in the session context

  • {load, list(string())} --- Loads files from the file system. Includes the first one in the list.

  • reload --- Reloads the currently loaded files.

  • {set, Option :: atom(), Value :: list(term())} --- changes REPL's configuration (see {help, "set"} for more details)

  • help --- lists all available commands

  • {help, string()} --- returns the help text for the given command

  • {lookup, atom()} --- prints information about REPL's state or configuration

  • {disas, string()} --- parses a reference to a function and prints its FATE code

  • stop --- if at breakpoint, cancels the execution and rolls back all changes

  • {break, FileName :: string(), Line :: integer()} --- adds a breakpoint

  • {delete_break, integer()} --- removes a breakpoint with a given id

  • {delete_break_loc, string(), integer()} --- removes all breakpoints from the given file at the given line

  • continue --- resumes execution after a breakpoint stop

  • stepover --- proceeds to the next line in the current execution

  • stepin --- proceeds to the next line, or enters the function body if there is a function call upcoming

  • stepout --- resumes execution until the next breakpoint or current function return

  • location --- returns in-code location of current execution

  • {print_var, string()} --- returns in-code location of where the variable was introduced

  • print_vars --- returns values of all variables in scope

  • stacktrace --- returns the current stacktrace

  • {set_account, pubkey(), integer()} --- sets balance for an in-repl account

  • version --- returns version information

  • banner --- returns an ASCII "banner" presenting the REPL's logo and various version information

Cast

  • {update_filesystem_cache, #{string() => binary()}} --- updates REPL's perception of the file system to the provided map. If this is set, all include and file load instructions will ignore system's file system, and will use this map instead.

Functions

All above calls and casts are exposed as function calls for convenience. Additionally, the following are offered:

  • format --- formats outputs of other commands into renderable texts to be used by the render function

  • render --- renders a renderable output to a string using REPL's theme

  • banner --- returns a nicely rendered banner for CLI interfaces

  • input --- parses a text command and interprets it as one of the calls above. Useful for CLI-like interfaces.

  • prompt --- proposes prompt to display in the CLI based on the REPL's state. For example, the default is AESO> .

Build the project (the make step may need to be executed twice, see ):

æREPL usage patterns are highly inspired by. Most of the syntax is a direct adaptation of it to the needs of Sophia and FATE. This section shall provide an overview of the most fundamental features and typical workflows. If you find navigation clunky, please consider using.

its documentation
this issue
GHCi
rlwrap