Docs on simulate flag for AnteHandler

[rootulp]

Context

cosmos-sdk/types/handler.go

Lines 6 to 8 in 7799bba

	// AnteHandler authenticates transactions, before their internal messages are handled.
	// If newCtx.IsZero(), ctx is used instead.
	type AnteHandler func(ctx Context, tx Tx, simulate bool) (newCtx Context, err error)

Problem

No documentation exists for the simulate flag.

Proposal

Document what is the purpose of the simulate flag. Since the AnteHandler type is implemented by both antehandlers and posthandlers, it would be helpful if the docs explained how antehandlers (or posthandlers) should treat the simulate flag. For example: if simulate=true should a posthandler not make any modifications to state?

[rootulp]

// If newCtx.IsZero(), ctx is used instead.

On a related note, this line seems confusing. Where is ctx used instead of newCtx? Is this applicable to a chained AnteHandler? Why not enforce that AnteHandlers propagate the ctx from one to the next?

[alexanderbez]

@rootulp where do you suggest exactly we put this documentation? A godoc on the AnteHandler type?

[rootulp]

Yep exactly.