Usage Documentation and helper functions

[DragonDev1906]

While informative, the current README.md does not explain much about using the SDK. https://github.com/perun-network/erdstall-ts-sdk/blob/main/src/e2e/sdk_actions.ts does explain most of the things below, but it is not linked from the README.md and not in an easy-to-find place, thus I have not found it while looking how to implement an ETH deposit.

• The creation and initialization of a Client is shown, but not how a Session object can be created (or even what type it is or how/where to import it.
• Reading just the README.md and github pages it is hard to figure out how to correctly make a ETH/ERC20 deposit and wait for it to be done. This might be worth putting into the README.md, especially since waiting for the deposit to finish is not intuitive. The current README.md does not explain how to make an asset list for depositing ETH or how to correctly wait for the deposit to finish, for example. Perhaps it would even be useful to have a helper function for depositing a single token (like the deposit function used below)
• Checking the balance of an account - This is a pretty basic function that is (probably) needed by almost all projects. As such it might be worth adding a helper function client.getBalanceOf(address, token) or a function on the Account, that returns the balance as a bigint (or at least describe how to do it, see below how I implemented it, for example). Needing two .values and having to convert the token to a string first isn't intuitive. That would allow something like the following: client.getAccount(address).balance(token)

async function balanceOf(erdstall, address, token) {
        let accountData = await erdstall.getAccount(address)
        let amount = accountData.values.values.get(token.toString())
        if (amount === undefined)
                return 0
        else
                return amount.value
}

A different point, but it might be useful to (in addition to client.on and client.once) have the ability to just delay execution until an event happened, instead of having to use a callback with client.once: let receipt = await client.waitForEvent("receipt"). As shown in the example below this is possible but not as nice to use/must be implemented if needed. Maybe even add an optional callback that is called to see if the given event value/object is what the user is waiting for. This would make chaining multiple calls (e.g. an offChainTransfer and getAccount calls) using async/await easier. (it could also be that waiting for the receipt is not needed here, I'm not sure)

// await erdstallEvent(erdstall, "receipt")
async function erdstallEvent(erdstall, name) {
        return new Promise((resolve, reject) => {
                try {
                        erdstall.once(name, x => {
                                resolve(x)
                        })
                } catch (error) {
                        reject(error)
                }
        })
}

// Example usage
async function run(erdstall) {
        await deposit(erdstall, ETH_TOKEN, BigInt(100))
        await printBalanceOf(erdstall, address, ETH_TOKEN, "WEI")
        await printBalanceOf(erdstall, address2, ETH_TOKEN, "WEI")

        // Make an off-chain transaction, waiting for offChainTransferTo (erdstall.transferTo) to finish, i.e. getting the receipt does not wait long enough for the upcomming printBalanceOf calls to get the new balances. Though waiting on any receipt probably isn't a good solution.
        await offChainTransferTo(erdstall, address2, ETH_TOKEN, 50)
        await erdstallEvent(erdstall, "receipt")

        // Print balances again
        await printBalanceOf(erdstall, address, ETH_TOKEN, "WEI")
        await printBalanceOf(erdstall, address2, ETH_TOKEN, "WEI")
}

async function offChainTransferTo(erdstall, toAddress, token, amount) {
        const assets = new Assets({
                token: token,
                asset: new Amount(amount)
        })
        const receipt = await (erdstall.transferTo(assets, toAddress)).receipt
        return receipt
}

[RmbRT]

Await events via await client.next("event-name", [timeout]).