Create transaction editing experience in a soroban tx edit command

[janewang]

Enable transaction editing in text form (in JSON and TOML)
Design doc

[leighmcculloch]

The goal of this issue is to replicate the stc transaction editing user experience.

The design doc linked above appears to focus more on the tx building flow which is being covered by this other issue:

• Enable transaction creation for critical classic commands #1437

Where-as this issue is focused on a tx text editing experience.

We have some decisions to make:

• Data format: Should we use the same data format as stc which is SEP-11? Or use JSON? JSONC? JSON5? TOML? JSON-GRON?

• Behaviors: How should the editing the behave, like stc, or differently?

Before anyone works on this feature, highly recommend using stc to get a first hand experience of how the tool works as it has subtle features that make a big difference to the editing experience.

[leighmcculloch]

Here are some examples of how the different formats fair:

XDR:

AAAAAgAAAAArFkuQQ4QuQY6SkLc5xxSdwpFOvl7VqKVvrfkPSqB+0AAAAGQApSmNAAAAAQAAAAEAAAAAW4nJgAAAAABdav0AAAAAAQAAABZFbmpveSB0aGlzIHRyYW5zYWN0aW9uAAAAAAABAAAAAAAAAAEAAAAAQF827djPIu+/gHK5hbakwBVRw03TjBN6yNQNQCzR97QAAAABVVNEAAAAAAAyUlQyIZKfbs+tUWuvK7N0nGSCII0/Go1/CpHXNW3tCwAAAAAX15OgAAAAAAAAAAFKoH7QAAAAQN77Tx+tHCeTJ7Va8YT9zd9z9Peoy0Dn5TSnHXOgUSS6Np23ptMbR8r9EYWSJGqFdebCSauU7Ddo3ttikiIc5Qw=

SEP-11:

type: ENVELOPE_TYPE_TX
tx.sourceAccount: GAVRMS4QIOCC4QMOSKILOOOHCSO4FEKOXZPNLKFFN6W7SD2KUB7NBPLN
tx.fee: 100
tx.seqNum: 46489056724385793
tx.timeBounds._present: true
tx.timeBounds.minTime: 1535756672 (Fri Aug 31 16:04:32 PDT 2018)
tx.timeBounds.maxTime: 1567292672 (Sat Aug 31 16:04:32 PDT 2019)
tx.memo.type: MEMO_TEXT
tx.memo.text: "Enjoy this transaction"
tx.operations.len: 1
tx.operations[0].sourceAccount._present: false
tx.operations[0].body.type: PAYMENT
tx.operations[0].body.paymentOp.destination: GBAF6NXN3DHSF357QBZLTBNWUTABKUODJXJYYE32ZDKA2QBM2H33IK6O
tx.operations[0].body.paymentOp.asset: USD:GAZFEVBSEGJJ63WPVVIWXLZLWN2JYZECECGT6GUNP4FJDVZVNXWQWMYI
tx.operations[0].body.paymentOp.amount: 400004000 (40.0004e7)
tx.ext.v: 0
signatures.len: 1
signatures[0].hint: 4aa07ed0 (GAVRMS4QIOCC4QMOSKILOOOHCSO4FEKOXZPNLKFFN6W7SD2KUB7NBPLN)
signatures[0].signature: defb4f1fad1c279327b55af184fdcddf73f4f7a8cb40e7e534a71d73a05124ba369db7a6d31b47cafd118592246a8575e6c249ab94ec3768dedb6292221ce50c

JSON (using stellar xdr decode ...):

{
  "tx": {
    "tx": {
      "source_account": "GAVRMS4QIOCC4QMOSKILOOOHCSO4FEKOXZPNLKFFN6W7SD2KUB7NBPLN",
      "fee": 100,
      "seq_num": 46489056724385793,
      "cond": {
        "time": {
          "min_time": 1535756672,
          "max_time": 1567292672
        }
      },
      "memo": {
        "text": "Enjoy this transaction"
      },
      "operations": [
        {
          "source_account": null,
          "body": {
            "payment": {
              "destination": "GBAF6NXN3DHSF357QBZLTBNWUTABKUODJXJYYE32ZDKA2QBM2H33IK6O",
              "asset": {
                "credit_alphanum4": {
                  "asset_code": "USD",
                  "issuer": "GAZFEVBSEGJJ63WPVVIWXLZLWN2JYZECECGT6GUNP4FJDVZVNXWQWMYI"
                }
              },
              "amount": 400004000
            }
          }
        }
      ],
      "ext": "v0"
    },
    "signatures": [
      {
        "hint": "4aa07ed0",
        "signature": "defb4f1fad1c279327b55af184fdcddf73f4f7a8cb40e7e534a71d73a05124ba369db7a6d31b47cafd118592246a8575e6c249ab94ec3768dedb6292221ce50c"
      }
    ]
  }
}

GRON:

json = {};
json.tx = {};
json.tx.signatures = [];
json.tx.signatures[0] = {};
json.tx.signatures[0].hint = "4aa07ed0";
json.tx.signatures[0].signature = "defb4f1fad1c279327b55af184fdcddf73f4f7a8cb40e7e534a71d73a05124ba369db7a6d31b47cafd118592246a8575e6c249ab94ec3768dedb6292221ce50c";
json.tx.tx = {};
json.tx.tx.cond = {};
json.tx.tx.cond.time = {};
json.tx.tx.cond.time.max_time = 1567292672;
json.tx.tx.cond.time.min_time = 1535756672;
json.tx.tx.ext = "v0";
json.tx.tx.fee = 100;
json.tx.tx.memo = {};
json.tx.tx.memo.text = "Enjoy this transaction";
json.tx.tx.operations = [];
json.tx.tx.operations[0] = {};
json.tx.tx.operations[0].body = {};
json.tx.tx.operations[0].body.payment = {};
json.tx.tx.operations[0].body.payment.amount = 400004000;
json.tx.tx.operations[0].body.payment.asset = {};
json.tx.tx.operations[0].body.payment.asset.credit_alphanum4 = {};
json.tx.tx.operations[0].body.payment.asset.credit_alphanum4.asset_code = "USD";
json.tx.tx.operations[0].body.payment.asset.credit_alphanum4.issuer = "GAZFEVBSEGJJ63WPVVIWXLZLWN2JYZECECGT6GUNP4FJDVZVNXWQWMYI";
json.tx.tx.operations[0].body.payment.destination = "GBAF6NXN3DHSF357QBZLTBNWUTABKUODJXJYYE32ZDKA2QBM2H33IK6O";
json.tx.tx.operations[0].source_account = null;
json.tx.tx.seq_num = 46489056724385793;
json.tx.tx.source_account = "GAVRMS4QIOCC4QMOSKILOOOHCSO4FEKOXZPNLKFFN6W7SD2KUB7NBPLN";

JSON5:

{
  tx: {
    tx: {
      source_account: 'GAVRMS4QIOCC4QMOSKILOOOHCSO4FEKOXZPNLKFFN6W7SD2KUB7NBPLN',
      fee: 100,
      seq_num: 46489056724385790,
      cond: {
        time: {
          min_time: 1535756672,
          max_time: 1567292672,
        },
      },
      memo: {
        text: 'Enjoy this transaction',
      },
      operations: [
        {
          source_account: null,
          body: {
            payment: {
              destination: 'GBAF6NXN3DHSF357QBZLTBNWUTABKUODJXJYYE32ZDKA2QBM2H33IK6O',
              asset: {
                credit_alphanum4: {
                  asset_code: 'USD',
                  issuer: 'GAZFEVBSEGJJ63WPVVIWXLZLWN2JYZECECGT6GUNP4FJDVZVNXWQWMYI',
                },
              },
              amount: 400004000,
            },
          },
        },
      ],
      ext: 'v0',
    },
    signatures: [
      {
        hint: '4aa07ed0',
        signature: 'defb4f1fad1c279327b55af184fdcddf73f4f7a8cb40e7e534a71d73a05124ba369db7a6d31b47cafd118592246a8575e6c249ab94ec3768dedb6292221ce50c',
      },
    ],
  },
}

TOML:

[tx.tx]
source_account = "GAVRMS4QIOCC4QMOSKILOOOHCSO4FEKOXZPNLKFFN6W7SD2KUB7NBPLN"
fee = 100
seq_num = 46_489_056_724_385_790
ext = "v0"

[tx.tx.cond.time]
min_time = 1_535_756_672
max_time = 1_567_292_672

[tx.tx.memo]
text = "Enjoy this transaction"

[[tx.tx.operations]]
[tx.tx.operations.body.payment]
destination = "GBAF6NXN3DHSF357QBZLTBNWUTABKUODJXJYYE32ZDKA2QBM2H33IK6O"
amount = 400_004_000
[tx.tx.operations.body.payment.asset.credit_alphanum4]
asset_code = "USD"
issuer = "GAZFEVBSEGJJ63WPVVIWXLZLWN2JYZECECGT6GUNP4FJDVZVNXWQWMYI"

[[tx.signatures]]
hint = "4aa07ed0"
signature = "defb4f1fad1c279327b55af184fdcddf73f4f7a8cb40e7e534a71d73a05124ba369db7a6d31b47cafd118592246a8575e6c249ab94ec3768dedb6292221ce50c"

[leighmcculloch]

My experience of the above examples is that:

• JSON is very verbose, but would be most appropriate for any interaction with non-human tools.
• TOML is quite difficult to intuitively understand because of a transactions many layers of nested tables with the operations, and will get worse for more complex transactions.
• SEP-11 is truly the most succinct and highest information to noise ratio but has no interoperability with other tools.
• Flattened JSON (e.g. GRON) is the closest to SEP-11 while preserving the XDR-JSON field names, and may be easier to develop.

I think we should probably support two formats, JSON (secondary), and SEP-11 (primary) or a GRON-like format (primary) mimicking SEP-11's experience.

We would benefit from an approach that'll work with all XDR types out-of-the-box. And so SEP-11 might be more difficult to achieve that because SEP-11 is focused on transactions only, where-as a GRON-like format which is really just flattened JSON may be more achievable with a similar user experience. We could explore how compatible SEP-11 is with other XDR types as a way to help make this decision.

Do others have thoughts?

[github-actions]

This issue is stale because it has been assigned for 30 days with no activity. It will be closed in 30 days unless the stale label is removed, and the assignee is removed or updated.

[fnando]

the good thing about JSON is that you can count on JSON schema completion within your editor of choice. I'm not sure the same would be available for other formats.

[github-actions]

This issue is stale because it has been assigned for 30 days with no activity. It will be closed in 90 days unless the stale label is removed, and the assignee is removed or updated.

[janewang]

Completed and released in v22.6.0: #1893