New command `stellar tx fetch <HASH>`

[ifropc]

trafficstars

Command description

Command that uses RPC getTransaction endpoint

Command flags

Optional --output json flag that changes output format to JSON (printing result object)

Command return value

Print transaction info in human readable format, for example:

status: Success
<..>
Envelope: <Parsed envelope XDR>
Result: <Parsed Result XDR>
Result Meta: <Parsed Result Meta>

[leighmcculloch]

I don't feel strongly but I think I prefer fetch over get. The existing commands use fetch term, like fetching wasm.

[leighmcculloch]

Optional --json flag

This should be --output json for consistency and the existing commands.

It also means from a CLI UI design every time we add a new output format it doesn't require adding another top level option to the command.

[ifropc]

Good points, let me update this and other tasks. Strongly agree about consistency

[janewang]

Discussed today to be able to better present fees

[leighmcculloch]

Discussed today to be able to better present fees

Could more be shared about what was decided what this means?

[elizabethengelman]

@leighmcculloch We discussed this in the DevX meeting last week, and I think that @janewang put some info in the meeting doc.

As a quick summary, we decided to prioritize the stellar tx fetch <TX_HASH> to command next, and realized that it would be a good place to display transaction fees. Jane also mentioned that it would be great to output a table like this https://developers.stellar.org/docs/learn/fundamentals/fees-resource-limits-metering, and that maybe we could have different flags for just displaying the fee, vs displaying the whole transaction.

Looking at the rpc getTransaction result, it seems like we'll be able to get the fee from decoding the transaction's resultXdr.

[leighmcculloch]

It sounds like the fetch command will output more than one piece of information.

There's a lot of ways to shape this API. Thinking about the context of where this command is being added, the stellar tx fetch command lives under the stellar tx which is a set of commands that are all about working with the TransactionEnvelope and being composable. So it's reasonable to expect the output to be only a TransactionEnvelope, and that seems like a worthy workflow, to retrieve a transaction envelope given a hash.

Considering a few different ways to present the API:

1‍⃣ There could be subcommands for fetching different things about the tx, such as the tx result, tx meta, etc. e.g. stellar tx fetch result, stellar tx fetch meta, or stellar tx fetch envelope. In this case envelope could be the default so that calling stellar tx fetch did the envelope for the common case, but I think that could make the others undiscoverable.

2‍⃣ There could be top level sub commands. e.g. stellar tx fetch, stellar tx-result fetch, stellar tx-meta fetch, etc. That feels a bit odd to me though.

3‍⃣ There could be just the one command that outputs everything, which I think is what's being suggested, and add an --output json be added and then folks can use other tools like jq to extract relevant information. e.g. stellar tx fetch --output json | jq '.envelope'.

4‍⃣ If this is really an rpc frontend, maybe it's time we implement one in the cli. e.g. stellar rpc getTransaction --output json|table|markdown|text.

❓ What other alternatives are there?

I think 1‍⃣ fits well with the current arrangement of stellar tx commands.

[elizabethengelman]

What we currently have implemented for fetching ledger entries in #2012 is kind of a combo of 1‍⃣ and 2‍⃣ : stellar ledger entry fetch <account, contract, config, etc>

So we could also do something along those lines with: stellar tx fetch stellar tx result fetch stellar tx envelope fetch

That being said, I do wonder if 4‍⃣ makes sense. A couple of positives for that change:

• It seems that other blockchains allow for this direct-from-cli rpc interaction, which is pretty helpful in exploring when you're not sure exactly what data you want.
• It also would be good from a documentation perspective, in that https://developers.stellar.org/docs/data/apis/rpc/api-reference/methods/getTransaction already handles documenting the rpc methods, and if the cli tool follows those functions it would be clearer what would be returned, etc.
• This is more consistent with Lab's ux

[elizabethengelman]

I'm thinking about spiking out a stellar rpc command, but I am thinking that it could look something like this for ledger entries:

• stellar rpc get-ledger-entries account <ACCOUNT>
• stellar rpc get-ledger-entries contract <CONTRACT>
• stellar rpc get-ledger-entries config <ID>
• stellar rpc get-ledger-entries claimable-balance <ID>
• stellar rpc get-ledger-entries liquidity-pool <ID>
• stellar rpc get-ledger-entries wasm <HASH>

Update: spike pr https://github.com/stellar/stellar-cli/compare/spike/rpc?expand=1

[elizabethengelman]

After our meeting today, we've decided to not include an rpc subcommand, since we are not planning to map the rpc interface directly in the CLI. Instead we'll use a similar format as is being used for ledger entries.

• stellar tx fetch <HASH> - will return the envelope by default
• stellar tx fetch envelope <HASH> - should we also include this subcommand, though fetch returns an envelope?
• stellar tx fetch meta <HASH>
• stellar tx fetch result <HASH>

[leighmcculloch]

I think both command structures can co-exist and have their benefits, so I don't think we need to choose between them either, and they can be prioritized independently.

With the rpc api we need to think holistically about how all the rpc methods would be supported, so having a clear pattern for how method params are made into options on the command line would be a good place to start I think, if we spend time on that.

With the stellar tx fetch api, above looks good. I think the envelope subcommand can be dropped. It'd help discovery of the other subcommands if the stellar tx fetch displays the help if no hash is provided, rather than erroring.

[elizabethengelman]

I think both command structures can co-exist and have their benefits, so I don't think we need to choose between them either, and they can be prioritized independently.

Great point! I should say that we decided not to prioritize the rpc subcommand right now. Do you think it's worth creating an issue to track discussion for that separately?

With the stellar tx fetch api, above looks good. I think the envelope subcommand can be dropped. It'd help discovery of the other subcommands if the stellar tx fetch displays the help if no hash is provided, rather than erroring.

Sounds good!

[github-actions[bot]]

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.