ABI-compliant app routing

[jasonpaulos]

Summary

Provide a way for an application to handle requests in compliance with https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0004.md#implementing-a-method

Scope

This might look like an ABIRouter object that you can use to build up the different routes. For example:

router = ABIRouter()

router.onBareAppCall(OnComplete.NoOp, handleCreate, creation=True)
router.onBareAppCall(OnComplete.OptIn, handleOptIn)
router.onBareAppCall([OnComplete.CloseOut, OnComplete.ClearState], handleCloseOut)
router.onBareAppCall([OnComplete.Update, OnComplete.Delete], handleUpdateOrDelete)

router.onMethodCall("add(uint64,uint64)uint128", handleAdd)
router.onMethodCall("multiply(uint64,uint64)uint128", handleMultiply)
router.onMethodCall("optInAndAdd(uint64,uint64)uint128", handleOptInAndAdd, OnComplete.OptIn)
router.onMethodCall("createWithAMethod()string", handleCreateWithAMethod, creation=True)

approvalAST, clearStateAST = router.buildPrograms()

onBareAppCall can be used to register a bare app call (defined in the ABI as a call with no arguments or return value). The allowed on completion actions must be specified, as well as whether the bare call can be invoked during creation or not.

onMethodCall can be used to register a method call. By default OnComplete.NoOp will be the only allowed on completion action, but others may be specified. Additionally, you can pass in a value for creation if this method call should be invoked during app creation or not.

Ideally the router would also unpack the arguments and pass them to the handler function, as well as take any return value from the handler function and prefix and log it appropriately. Though this might require some more thought to implement properly.

buildPrograms would construct ASTs for both the approval and clear programs based on the inputs to the router. If any routes can be accessed with OnComplete.ClearState, these routes will be added to the clear state program.

[ahangsu]

Some minor thoughts to write up in the thread: recall in #153 that we introduced an option in Subroutine such that one can specify the subroutine ABI method signature.

We can retrieve the ABI method sig from registered handler in onMethodCall, so we don't have to write the method sig again.

What do you think?

[jasonpaulos]

@ahangsu I think that is a good idea, but it's probably better implemented at a higher level.

If we decide to add onto this feature later with an easier to use way of defining contracts, then that would likely be a better place to make sure the same ABI method signature is used everywhere. For example this could look like:

@ABIContract
class MyContract:

    @ABIMethod("add(uint64,uint64)uint128")
    def add(a, b):
        pass

approvalAST, clearStateAST = MyContract.buildPrograms()

And as of right now, there's no constraint that the ABIRouter has to be used with subroutines

[ahangsu]

Wait I am confused... Could you give some counterexamples that ABIRouter is applied to something other than subroutines, under onMethodCall? I can only think of it be applied over some subroutines, to feed some application args. @jasonpaulos

[jasonpaulos]

My bad, I originally wrote this issue with the idea that any expression (not necessarily a subroutine) could be used to "handle" a route.

But then I added the paragraph:

Ideally the router would also unpack the arguments and pass them to the handler function, as well as take any return value from the handler function and prefix and log it appropriately. Though this might require some more thought to implement properly.

And it seems like that would require only subroutines to work with the router, since no other expression would be able to take arguments like that.

So perhaps we do want to restrict the handlers to being subroutines?

[ahangsu]

Let's sort this out clear a little bit:

• for onBareAppCall: it is possible (and totally doable) to allow a sequence of expressions to handle (so long as it does not take arguments), or a subroutine with no args and no return (it only matter if we want only subroutine or not).
• for onMethodCall: the current situation to me is that we generally want to support redirecting application args to handler, and it would help us a lot if the handler has a unified way to take args, so subroutine is a good fit (and probably only fit here).

In this way, we see a possibility to change onMethodCall to be a decorator over subroutine, which helps readability and better syntax on highest level. Does that sounds reasonable to you?

The issue's main focus is to provide the router mechanism rather than a better interface.