Refresh events CAP

core/cap-0046-08.md

@@ -28,70 +28,47 @@ This CAP is aligned with the following Stellar Network Goals:
 * The Stellar Network should make it easy for developers of Stellar projects to create highly usable products
 
 ## Abstract
-This CAP provides host functions for contracts to write messages that will be put
-into `TransactionMeta`. It provides a way to cryptographically verify the
-contents of `TransactionMeta`, and also moves `TransactionResult` into the meta
-so they stop taking space in the archives.
+This CAP provides host functions for contracts to write events that will be put
+into `TransactionMeta`. It also provides a way to cryptographically verify the events.
 
 ## Specification
 
 ### Contract Events
-This CAP makes a change to `TransactionMeta` and `TransactionResult` that will allow
-a user to cryptographically verify anything in `TransactionMetaV3`.
-`TransactionMetaV3` will store separate SHA256 hashes for ledger entry changes and
-contract events, and the hash of those hashes will be stored in `TransactionResultPairV2`.
-
-How can this be used? The `LedgerHeader` contains the hash of the
-`TransactionResultSetV2`, so the user will first gather all results from the desired
-ledger, hash them, and verify that the hash matches what's in the `LedgerHeader`.
-With `TransactionResultSetV2` verified, the user can then find the `TransactionMetaV3`
-for the transaction they're interested in, hash just contract events, combine
-that hash with the other hashes in `TransactionMetaV3` and then verify it against
-the hash stored in `TransactionResultPairV2`.
+We introduced a `TransactionMetaV3`, which has an optional
+`SorobanTransactionMeta` struct that should be set for Soroban transactions.
+This contains a `events` vector of `ContractEvent`, which will contain the
+events emitted by the host and contract.
 
-#### Host function
-The `contract_event` host function specified in [CAP-0046-03](./CAP-0046-03.md#context-host-functions)
-can be used to create events in contracts.
+### Cryptographic verification
 
-#### Stop storing TransactionResults in archives
-This CAP also removes the `TransactionResult` from the archives by using
-`TransactionHistoryResultEntryV2`. Instead, the `TransactionResult` will be
-stored in `TransactionMetaV3`, while the hash of `TransactionResult` will be
-stored in `TransactionMetaV3::hashes`. With this change, the archives will take less
-space, but it does mean that the results will need to be be pulled from the
-meta. Cryptographic verification would work just like contract events described
-above, except you would match against the `TransactionResult` hash stored in
-`TransactionMetaV3::hashes`.
+`TransactionMeta` is not hashed into the ledger, which is an issue because the
+events can't be cryptographically verified, and tests that replay historical
+transactions will not catch instances where the events emitted have changed. To
+fix this issue, `InvokeHostFunctionOp` returns the SHA-256 hash of
+`InvokeHostFunctionSuccessPreImage`, which contains the SCVal return value of
+the top level contract call, and the vector of events emitted. This makes the
+events part of the protocol. 
 
-`LedgerHeader::txSetResultHash` will also be updated to store the hash of
-`TransactionResultSetV2`.
 
-TODO: Does this work with InnerTransactionResultPair?
+### Diagnostic events
+The host can also emit diagnostic events, which are not part of the protocol and
+do not count towards metering and fees. These events are in a separate
+`diagnosticEvents` vector in `SorobanTransactionMeta` with `ContractEventType`
+`DIAGNOSTIC`. To be able to order diagnostic and non-diagnostic events,
+`diagnosticEvents` will also contain all of the protocol events. 
 
-### TransactionMeta Normalization
-TODO
+#### Host function
+The `contract_event` host function specified in [CAP-0046-03](./CAP-0046-03.md#context-host-functions)
+can be used to create events in contracts.
 
 ### XDR Changes
 
 See the XDR diffs in the Soroban overview CAP, specifically those covering
 changes to transaction meta and results, result sets, history entries, and
 contract events.
 
-## Design Rationale
-
-### TransactionResult in TransactionMeta
-By removing the `TransactionResult` from the archives, the archives will take
-less space going forward. The results will still be available in thr meta, so
-there is no functionality lost here.
 
-### TransactionMeta hashes
-This CAP allows for the cryptographic verification of `TransactionMetaV3` by
-including the SHA256 hash of the `hashes` field in `TransactionResultPairV2`.
-This allows the user to verify the authenticity of any of the subcomponents of
-`TransactionMetaV3`. The components are hashed separately so the user only needs
-to hash the components they care about, and assume the other component hashes
-are authentic. If any of the component hashes are incorrect, the verification
-will fail. 
+## Design Rationale
 
 ### Different event types
 Each event host function uses a different type. This gives downstream users
@@ -103,16 +80,15 @@ created contract.
 
 ### Topics
 In addition to the `SCVal data` in `ContractEvent`, we also provide an `SCVec`
-that the user can fill out with smaller values so downstream systems can
-provide more narrow filtering and subscription options without prior knowledge
-of the `data` format.
-
-TODO: Specify how topics will be limited in size.
+that the user can fill out with smaller values so downstream systems can provide
+more narrow filtering and subscription options without prior knowledge of the
+`data` format. There can only be four topics, and if the type is `Bytes`, cannot
+be more than 64 bytes.
 
 ## Protocol Upgrade Transition
 
 ### Backwards Incompatibilities
-Any downstream system consume `TransactionResult` will need to pull this information from the `TransactionMeta` instead.
+None
 
 ### Resource Utilization
 TBD