New Simulate Endpoint

With this release, Algorand is introducing a new simulate REST endpoint that enhances contract evaluation by using live chain data to simulate either one or multiple grouped transactions. State changes are reflected within atomic groups of transactions. This means when using simulate to perform unit test, setting up state can most likely be done once and multiple test executed against the state data. Additionally, when moving to environments such as TestNet and MainNet, you can execute against live chain data without actually permanently altering the blockchain. This improves debugging capabilities and also has the added benefit of exposing method calls against a smart contract with no transaction fees. As with all transactions, calling a smart contract requires that a transaction fee be paid for the transaction. However, with the simulate REST endpoint, the transaction is never actually issued to the network, thereby avoiding the transaction fee, while still returning live chain state data.

While simulate endpoints support non-ABI contracts, use of the Atomic Transaction Composer (ATC) API with ABI-compliant contracts will return decoded ABI return values. The ATC API has been improved to fully support the simulate endpoint. For example, the python code below creates an atomic group of three transactions using the ATC. The simulate endpoint is executed with the ATC’s simulate method.

   atc = AtomicTransactionComposer()
   atc.add_method_call(app_id, method, acct.address, sp, acct.signer, [2, 3])
   atc.add_method_call(app_id, method, acct.address, sp, acct.signer, [3, 3])
   atc.add_method_call(app_id, method, acct.address, sp, acct.signer, [4, 3])


   result: SimulateAtomicTransactionResponse = atc.simulate(client)
   print(f"would succeed? {result.would_succeed}")
   print(f"failed at? {result.failed_at}")
   print(f"failure message? {result.failure_message}")


   print("abi results ")
   for r in result.abi_results:
       print(f"\t{r.tx_id} ({r.method.name}) => {r.return_value}")
       print(f"\tMissing signature? {r.missing_signature}")

The simulate endpoint provides some general feedback on the entire group of transactions and more specific information on each transaction in the group. The general information returned includes a boolean (result field would_succeed) that informs the caller that the group would succeed or not based on the current state of the chain and the provided transaction(s). If the group of transactions would fail, the specific transaction index will be returned in the result field failed_at. The failure message of a failed transaction will also be returned in the result failure_message field.

The specific information for each transaction is returned in the abi_results field when using the ATC. The simulate API wraps this result with additional information. For example, the missing_signature field contains a true or false value verifying whether a transaction was successfully signed.

If the above code were calling a contract’s add method three times with the specified parameters, the results would be as shown below.

would succeed? True
failed at? None
failure message? 
abi results 
        Z6JZ5X6K4PAWCZFGXRNI67BIX7LK26DSIF7EW36QHN3XPYBB7CUA (add) => 5
        Missing signature? False
        DN6P5BLJZ3VEEYTZQEIRNGFCIG5GR4TNBG2LDEVISCGCEC6EUBLA (add) => 6
        Missing signature? False
        RQHHAFC4THZ77WERFKQZJKJQ447UZNAMRXQRUERLTDBLDMYKJYOQ (add) => 7
        Missing signature? False

If an additional transaction is added to the above group with a call to the smart contact’s div method, attempting to divide by zero would result in the following.

would succeed? False
failed at? [3]
failure message? transaction XOC56IV55YNPCSQUZ7ZIZEXSAQAXV2LEBV54D2GDBPR2WNTLDRJA: logic eval error: / 0. Details: pc=167, opcodes=frame_dig -2
frame_dig -1
/

abi results 
        PZBEYJZ4LUFWRQIXQXRLCKLFYVEEGSFTRBH5H4T4E7FUHOZ2MF4A (add) => 5
        Missing signature? False
        2QBJDFLA3O356UKRK4GNGITD6DE4E73DJIM5NIG2FV5TTQAELFEA (add) => 6
        Missing signature? False
        X2OQI2PLGLNWM6FHW4FVDWYG5NAVKB2K34FUN772O25XCGEPEJUQ (add) => 7
        Missing signature? False
        XOC56IV55YNPCSQUZ7ZIZEXSAQAXV2LEBV54D2GDBPR2WNTLDRJA (div) => None
        Missing signature? False

Note that the fourth transaction failed and returned nothing. The reason it failed is because of a divide by 0 that occurred after loading the two parameters to the subroutine (frame_dig opcodes) and the final opcode shows the actual failing opcode. In this example, that would be /.

This is just the first release of the simulate endpoint and future enhancements are already in the works. Make sure to check out Anne’s post for more details!

Follower Node

Algorand is releasing a new type of node that is primarily intended to collect data for the Indexer or Conduit processes. This node uses the standard algod process and can be started using goal and a new config.json option. The follower node adds the capability to do a controlled synchronization by pausing to allow specific data points to be retrieved. For example, if you want to know the balance of an account at a specific round that has already passed on MainNet. To set up a follower node, set EnableFollowMode to true in the node’s config.json file (see Node Profiles below for simplified installation).

The follower node will be made compatible with Conduit and Indexer in their next release, meaning you can sync with a follower node as opposed to an Archival node. Currently, the Indexer must connect to an Algorand node that is running in Archival mode, which stores all blocks locally. This is a significant cost in disk space as this is currently over a terabyte of data and growing. This should simplify setting up an Indexer or Conduit for data collection.

The sync round for the follower node is used to control where it is paused and can be managed with three new REST endpoints: retrieve ( GET /v2/ledger/sync), set ( POST /v2/ledger/sync/{round}), or delete ( DELETE /v2/ledger/sync). If the sync round is deleted the follower node will sync to the latest round of the network. Getting the sync round returns the current setting for sync round which by default starts at 0. This means when first starting, the follower defaults to pause, which allows early blocks to be interrogated. It is important to note that when a sync round is set, the node will actually fetch blocks for that round plus a configurable number of rounds. The number of rounds can be set using the MaxAcctLookback setting, which can be set in the config.json. For performance reasons, setting this value to 64 works well.

API=$(cat ../data/algod.net)
APITOK=$(cat ../data/algod.token)

# Get the current sync round
TXINFO=$(curl -s -H "X-Algo-API-Token: $APITOK" "http://${API}/v2/ledger/sync")
echo $TXINFO

# Set the current sync round
TXINFO=$(curl -s -H "X-Algo-API-Token: $APITOK" -X POST "http://${API}/v2/ledger/sync/354999")
echo $TXINFO

# Delete the sync round
TXINFO=$(curl -s -H "X-Algo-API-Token: $APITOK" -X DELETE "http://${API}/v2/ledger/sync")
echo $TXINFO

The follower node also has added functionality that allows ledger state delta data to be read for a specific number of rounds. This number corresponds to the MaxAcctLookback setting. This ledger state delta data includes everything that was changed in the ledger in the specific round such as account balance changes, smart contracts created, box storage changes, global and local state changes, and assets created. To retrieve the ledger state delta, a new REST endpoint (‘/v2/deltas/{round}’) is available. If you set sync to 1000, blocks 1000-1063 ledger delta data will be available. If you attempt to read ledger data outside of this window, the REST call will result in a failure message. If you set the sync round to the currently connected network round, only that one block’s ledger delta will be available.

# example shell to get ledger delta for round 110000
# executed from algod bin directory

API=$(cat ../data/algod.net)
APITOK=$(cat ../data/algod.token)
TXINFO=$(curl -s -H "X-Algo-API-Token: $APITOK"  "http://${API}/v2/deltas/110000")
echo $TXINFO

Follower nodes remove the consensus logic and transaction processing capabilities of normal participation nodes. This means the follower will not accept transactions or allow consensus participation.

Node Profiles

Algorand nodes have many configuration parameters that affect the operation of the node which are explained in the documentation. For example an administrator may want a relay node as opposed to a participation node. See the developer documentation for more information on node types. To change these parameters, administrators can use a standard editor and modify the config.json (copied from config.json.example) file located in the data directory. Or administrators can use the algocfg CLI utility to pass in PV pairs to set a specific value in the configuration. With this release, the algocfg tool has been improved to provide a profiles command that allows administrators the ability to quickly setup a new node type without worrying about what parameters need to be changed.

Currently, algocfg supports profiles for relay, participation, development and conduit. The conduit profile effectively sets the parameters for a follower node described in the previous section of this article. This list of profiles will most likely expand in the future. To list out all profiles support run algocfg with the following options.

algocfg profile list 
participation  Participate in consensus or simply ensure chain health by validating blocks.
conduit        Provide data for the Conduit tool.
relay          Relay consensus messages across the network and support catchup.
development    Build on Algorand.

To set a specific profile use the following command.

algocfg profile set conduit -d <yourdatadir>

If you already have a config.json file when this command is executed you will be prompted to overwrite with the new version.

TEAL Macros

Algorand 3.15.0 now supports defining macros within TEAL source files. This can be done using the #define directive. This allows groups of opcodes to be assigned to a specific constant. For example, the following code could be used to create a divide by 10 constant using a macro.

#define divby10 int 10; /

.
.
int 100
divby10

Where this can be extremely useful is when doing complex data manipulation that requires many opcodes. In these instances, macros improve code readability and reuse for common TEAL operations. One example where macros are exceptionally beneficial is when encoding and decoding ABI data types. Take a look at this example that illustrates some of the ABI data type encoding and decoding operations using macros.