Structured output and multicall interface

[mkaput]

We plan to introduce an ability to output information from certain commands in JSON, to ease using
Protostar in scripts or IDEs. This feature will follow designs of Terraform
or kubectl / K8s Objects.

Affected commands

• protostar build
• protostar call
• protostar declare
• protostar deploy-account
• protostar invoke
• protostar test

How to turn JSON output on?

protostar declare ... --json

General format of output objects

All affected commands are supposed to output messages on stdout as NDJSON, that is:
a series of JSON objects, not formatted, separated by newline (\n).

{
  "type": "<command name>"
  // additional data will go here
}

The type field's purpose is to enable validating correct message objects are received on consumer
side.

Some commands may skip type though, if the returned object comes directly from other source. This will happen, for example, in protostar call

Most commands will output only one object, but output consumer logic should be prepared to handle
multiple objects in the future.

Any logs or extraneous messages will be routed to stderr.

The exact shape of message objects for each command is subject for further decisions making.

Multicall

We are also slowly thinking about providing a way to atomically execute multiple transactions via
UDC.
In general this should be possible with SDKs, but we plan to offer simpler interface in Protostar
to ease one-off calls etc.
This proposal has to take into account the future multicall command which will do this.
Because it is going to be very inconvenient to type multiple multicall commands in a single
protostar invocation, the plan is to shift towards document-oriented model in this particular
case.

{
  "type": "multicall",
  "network": "testnet",
  "account_address": "0xdeadbeef",
  "calls": [
    {
      "type": "invoke",
      // ...
    },
    {
      "type": "deploy",
      // ...
    }
    // ...
  ]
}

protostar multicall -i call.json

The format of multicall documents should closely follow format of output objects for consistency.
Again, the type field is for validation measures.
The exact shape of multicall document is subject for future changes.

In the future, it would be nice to introduce interactive user interface/wizard for multicall.

[kasperski95]

1. Currently, protostar GATEWAY_COMMAND isn't designed to work with protostar multicall, because protostar GATEWAY_COMMAND also sends the transaction.

2. I see a potential for name collisions with this approach ("type"). Also, I'd design the output to be an input to the next command and wouldn't include input data.

{
  "type": "<command name>"
  // additional data will go here
}

---

Alternative proposal

Expect the output of every program to become the input to another, as yet unknown, program. Don't clutter output with extraneous information.

protostar build "balance_contract"
| protostar create-deploy 
| protostar send
| protostar create-invoke --fn-name "increase_balance" -i 42
| protostar send
| protostar call "get_balance"

Multicall

protostar create-invoke 0x123 ... >> multicall-input.yaml
protostar create-invoke 0x321 ... >> multicall-input.yaml
protostar send multicall-input.yaml > transaction.yaml

NOTE: YAML is used here instead of JSON to make appending easier

Preparing a transaction and sending it are two orthogonal responsibilities. Mixing orthogonal responsibilities results in a code duplication (network arguments).

multicall-input.yaml

invoke-tx-payload:
  contract-address: "0x123"
  input:
    felt_arg: 1
    struct_arg:
      key1: 1
      key2: 2
invoke-tx-payload: 
  contract-address: "0x321"

transaction.yaml

tx:
  status: "ACCEPTED_ON_L2"
  hash: "0x123"

[mkaput]

We could use TOML's Array of Tables instead of YAML

[mkaput]

I do like the create-* commands approach for building multicall document!