Add doc/ledger-consensus-api.md

[erikd]

No description provided.

[JaredCorduan]

atOutSum isn't needed, it is easily computed from the tx. and if all you really need is the difference with atInputSum to figure out the deposits, we could just supply that instead.

[JaredCorduan]

This is really great, thanks for such a clear write-up! I think this would be straight-forward to implement with foldBlocks from the cardano-client-demo.

[kderme]

Computing this at Node may be impossible. The reason is that this requires the current UTxO before a Tx is applied, which won't be available to the Node when we request for a block. This can only be available after db-sync has received the block and applies it, as a ledger event.

Let me explain with an example:
Node tip is at Slot 10000 and db-sync requests block 100. The ledger state at slot 10000 can be used to produce the time metadata for block 100, because the time horizon for time metadata is pretty wide. However it has no way to resolve the inputs for block 100: the UTxO at slot 10000 is useless for this. The UTxO at slot 100 is also not enough, because it is already stale when a first transaction is applied. This can only be done in the general case as ledger events.

[erikd]

My idea was that the ledger would calculate this. It gets the next block from the LocalChainSync protocol, applies it, and then returns a new ledger state, with an annotated block which includes annotations with the data specified in that document..

However it has no way to resolve the inputs for block 100: the UTxO at slot 10000 is useless for this.

Unless the inputs have already been spent, they should still be part of the UTxO set before the block is applied. If they have already been spent at that time, the transaction is not valid anyway.

[kderme]

Unless the inputs have already been spent, they should still be part of the UTxO set before the block is applied

The TxOut may not exist yet, if it is created by a previous Tx on the same block. So the UTxO state before the block application is not enough in the general case. The only place where the correct UTxO is available is somewhere inside the applyBlock, at the point where a Tx is applied. The only way to make this available is with ledger events, which is, in my mind at least, metadata of a block application.

[erikd]

My idea is all predicated on there being a function like applyBlock but with a type signature:

applyAndAnnotateBlock :: LedgerState -> Block -> (LedgerState, [LedgerEvent])

where one of the constructors of LedgerEvent carries an AnnotatedBlock containing AnnotatedTxs.

[kderme]

Yes this is exactly what we need eventually. 50% of db-sync code could be removed by a function like this. Unfortunately applyblock is a black box for db-sync which only returns the LedgerState currently.