Design: IActionContext.PutLog

[moreal]

This discussion wants to suggest introducing IActionContext.EmitEvent method, a method to leave logs as TxExecution. It was inspired from emit <EVENT> syntax in solidity (i.e. Ethereum).

The event logs will help debugging the transaction and it'll help to show them in Web interface by saving them as transaction result and providing them through GraphQL. (Etherscan - Logs example)

Expected changes

Added APIs

• System.Action<string> IActionContext.PutLog { get; }.
• IReadOnlyList<string> ActionEvaluation.Logs { get; }
• IReadOnlyList<IReadOnlyList<string>> TxExecution.ActionLogsList { get; }
• IReadOnlyList<IReadOnlyList<string>> TxExecution.ActionLogsList { get; }
• (Libplanet.Explorer) query.explorer.transactionQuery.transactionResult.actionLogsList field (with [[String!]!] type).

Usage in actions

using Bencodex.Types;
class Sleep : IAction
{
  public IAccountStateDelta Execute(IActionContext context)
  {
    var states = context.PreviousStates;
    
    if (!(states.GetState(context.Signer) is { } state && state is Integer startBlockIndex))
    {
      context.PutLog($"Start sleeping");
      states = states.SetState(context.Signer, (Integer)context.BlockIndex);
    }
    else
    {
      context.PutLog($"Sleeping while {context.BlockIndex - startBlockIndex} blocks.");
    }

    return states;
  }
}

Implementation

See #2505.

[dahlia]

Would it be any more beneficial to have a structure like { string Event; IValue[] Arguments } than just Bencodex.Types.Dictionary? If we'd like to provide features depending on Event, a separate tag, like filtering on Event it would be definitely useful, but the current proposal seems lacking such feature. I'm not arguing that such feature should be implemented — rather, if we don't need to treat Event special it might be better to keep it simple IMHO.

[moreal]

Would it be any more beneficial to have a structure like { string Event; IValue[] Arguments } than just Bencodex.Types.Dictionary?

Maybe it doesn't. Ethereum's event and topic seems to be designed for client side subscription (listening events)¹. But, in our case, it doesn't. It's just for debugging after the transaction executed.

I just separated string Event property because I guessed every users will want to define event name (e.g. Attack, Sleep, Burnt) when logging events. But I lost the confidence while thinking more. If they want to check the transaction's progress, they can leave only Null.Values and debug with the number of events and the source. Or without any event keyword, they can debug with the source because they can guess.

This part seems a part of Libplanet's opinion. (i.e. Libplanet encourages you to design event like that).

I listed available methods I thought, please leave your opinion 🙏

• Bencodex.Types.Dictionary: It's free to attach event type or not. This event log type can have the readable definition of itself.
• Bencodex.Types.List: It's free to attach event log type or not. This event log type should be debugged with the source code because source code has its definition. However it will cost more less storage space.
• string Event, LogArgument[] Arguments: Force to define event type and restrict argument's type and size (LogArgument, tentative name)
  • type LogArgument = string<length=32> | Int64 | Address (or this runtime validation is too slow...)

Footnotes

1. https://docs.soliditylang.org/en/v0.8.17/contracts.html#events ↩

[dahlia]

Okay, fair enough. Then, this discussion would be more productive if you address the rationale (goals and non-goals) of the proposal. As the main purpose to emit them are not for publishing messages to subscribers (say, front-ends), but for recording debug logs, its design probably should be more similar to traditional application logging frameworks (e.g., Serilog, Log4j, Python's logging module) rather than EVM events.

[moreal]

I replaced the description with a new design and implementation.