Clarify Frame::HostFunction

[jonjove]

What problem does your feature solve?

The name here confuses me. I don't understand the intention. Based on the code, it looks like we are only using Frame::HostFunction as the initial frame when calling in via invoke_function (this behavior is fine). But the name suggests that we would push a Frame::HostFunction every time a host function is called, which we are not doing (this behavior is also fine). Perhaps we can come up with a name that indicates the actual usage?

What would you like to see?

A better name that indicates the actual usage.

What alternatives are there?

Leave the name as is, with some comments about what it actually means. I don't feel great about this though.

[smac711]

@jonjove will this need to be completed ahead of Meridian or can we de prioritize this work into a later iteration or just backlog it for now in now iteration?

[jonjove]

Backlog it, it's purely about code quality and is not observable to users.

[smac711]

@jonjove moving this to backlog to be prioritized into a later sprint.

[jayz22]

I get the confusion but the Frame definition is purely internal so maybe we just leave it as is and add some documentation in the code. Also this is also fairly engrained with the InvokeHostFunctionOp (https://soroban.stellar.org/docs/getting-started/invoking-contracts-with-transactions#invokehostfunctionop) definitions, which means entering the Host environment via one specific host function with three possible actions (invoke contract /create contract/update wasm), which is the basis of the soroban transactions.

Given this is hard to change, and the benefit is heavily out-weighted by potential confusion and adaptation cost. I'll move this to post-testnet to add better code documentations in the host.

[graydon]

@jayz22 I noticed this again while working with the Frame type recently and agree with Jon's position that it's too easy to read this as meaning "any time a host function is invoked". I would like to propose changing it to Frame::InitialInvokeHostFunctionOp or Frame::TopLevelInvokeHostFunctionOp or Frame::OutermostInvokeHostFunctionOp or something like that, for clarity.