Time management utilities

[cusma]

Problem

For some use cases, particularly when Smart Contract are based on time or blocks' height conditions, it is useful to conveniently "wait" for a given timestamp or block.

Moreover, when things run on a LocalNet in DevMode it is possible to "fast forward" both time and blocks.

It would be very useful if such methods could have a nice UX (a less boilerplate code).

Solution

Add to AlgorandClient and LocalNet (or some better place) convenient methods to fetch time/blocks, wait for time/blocks conditions, jump to time/block (in DevMode).

Proposal

Add to the AlgorandClient the following methods:

• getLastRound: returns the last committed round from Algod
• getLatestTimestamp: returns the latest UNIX timestamp committed with the last round from Algod
• waitUntilRound: is a "sleep" conditions that alts the execution until a given round is committed (it could leverage getLastRound)
• waitUntilTimestamp: is a "sleep" conditions that alts the execution until a given UNIX timestamp is committed (it could leverage getLatestTimestamp)

In order to speed up tests when things run LocalNet (in DevMode), the following methods can be added (not in AlgorandClient, since it's DevMode specific):

• blockWarp: generate blocks to jump directly to a given blocks' height (blocks are instantly generated as soon as a transaction is committed in DevMode)
• timeWarp: set a proper time offset to commit a block with the desired UNIX timestamp.

Specifically for timeWarp I'd suggest the following implementation to jump directly to toTimestamp:

1. Get the latestTimestamp with getLatestTimestamp
2. Set the timestamp offset with the Algod method to: toTimestamp - latestTimestamp
3. Generate a block to commit the desired offset (this could use blockWarp with a single block generation)
4. Reset the timestamp offset to 0

Pros and Cons

Pros: speed up test, less boilerplate code, nicer UX. Cons: none.

Dependencies

Algorand SDK and LocalNet in DevMode

[robdmoore]

My suggestion for the design of this would be a new NetworkManager class is added (similar to AppManager, AssetManager, etc.) with the following signatures from AlgorandClient:

• algorand.network.getLastRound()
• algorand.network.getLatestTimestamp()
• algorand.network.waitUntilRound()
• algorand.network.waitUntilTimestamp()
• algorand.network.localNet.blockWarp()
• algorand.network.localNet.timeWarp()

We could also proxy or maybe even move some of the methods on ClientManager like isTestNet() and potentially proxy some of the localnet specific things to hang off algorand.network.localNet. in other classes like localNetDispenser on AccountManager as one of a number of examples.

[robdmoore]

All of them should wrap the underlying algosdk types, similar to getById in AssetManager and getInformation in AccountManager and do the similar treatment like convert round numbers to bigint etc. to follow AlgorandClient conventions.