From d22d79ed12a8074eba53743a65a1111e61d18fdb Mon Sep 17 00:00:00 2001 From: Siddharth Suresh Date: Fri, 14 Jul 2023 16:51:16 -0700 Subject: [PATCH] Refresh events CAP --- core/cap-0046-08.md | 82 ++++++++++++++++----------------------------- 1 file changed, 29 insertions(+), 53 deletions(-) diff --git a/core/cap-0046-08.md b/core/cap-0046-08.md index 27fbb213c..e3aff94a6 100644 --- a/core/cap-0046-08.md +++ b/core/cap-0046-08.md @@ -28,48 +28,38 @@ 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 @@ -77,21 +67,8 @@ 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