Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added the event v2 translation engine description to aip-71.md #539

Merged
merged 1 commit into from
Jan 16, 2025
Merged

Added the event v2 translation engine description to aip-71.md #539

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
191 changes: 117 additions & 74 deletions aips/aip-71.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ created: 02/22/2024
## Summary

This AIP proposes a migration plan for all handle events (event v1) in Aptos Framework to module
events (event v2) and adding new events.
events (event v2) and adding new events. To facilitate a seamless migration process, this AIP also introduces the event v2 translation engine, which is a temporary REST Node API path to support the event v1 queries even after the event migration is enabled.

### Goals

Expand Down Expand Up @@ -49,86 +49,129 @@ The default migration strategy:

Migrated Events

| Module | Event v1 Name | Event v2 Name | ABI update |
|:---:|:---:|:---:|:---:|
|account.move|KeyRotationEvent|KeyRotation|+account:address |
|aptos_account.move|DirectCoinTransferConfigUpdatedEvent|DirectCoinTransferConfigUpdated| + account:address|
|coin.move|DepositEvent|Deposit|+ account:address|
|coin.move|WithdrawEvent|Withdraw|+ account: address|
|object.move|TransferEvent|Transfer| |
|aptos_governance.move|CreateProposalEvent|CreateProposal| |
|aptos_governance.move|VoteEvent|Vote| |
|aptos_governance.move|UpdateConfigEvent|UpdateConfig| |
|block.move|NewBlockEvent|NewBlock| |
|block.move|UpdateEpochIntervalEvent|UpdateEpochInterval| |
|aptos-token-objects/token.move|MutationEvent|Mutation|+ token:address|
|aptos-token-objects/collection.move|MutationEvent|Mutation|+ collection:address|
|aptos-token-objects/collection.move|BurnEvent|Burn| + previous_owner|
|aptos-token-objects/collection.move|MintEvent|Mint|+ collection:address|
|multisig_account.move|AddOwnersEvent|AddOwners|+ account: address|
|multisig_account.move|RemoveOwnersEvent|RemoveOwners|+ account: address|
|multisig_account.move|UpdateSignaturesRequiredEvent|UpdateSignaturesRequired|+ account: address|
|multisig_account.move|CreateTransactionEvent|CreateTransaction|+ account: address|
|multisig_account.move|VoteEvent|Vote|+ account: address|
|multisig_account.move|ExecuteRejectedTransactionEvent|ExecuteRejectedTransaction|+ account: address|
|multisig_account.move|TransactionExecutionSucceededEvent|TransactionExecutionSucceeded|+ account: address|
|multisig_account.move|TransactionExecutionFailedEvent|TransactionExecutionFailed|+ account: address|
|multisig_account.move|MetadataUpdatedEvent|MetadataUpdated|+ account: address|
|reconfiguration.move|NewEpochEvent|NewEpoch| |
|stake.move|RegisterValidatorCandidateEvent|RegisterValidatorCandidate| |
|stake.move|SetOperatorEvent|SetOperator| |
|stake.move|AddStakeEvent|AddStake| |
|stake.move|ReactivateStakeEvent|ReactivateStake| |
|stake.move|RotateConsensusKeyEvent|RotateConsensusKey| |
|stake.move|UpdateNetworkAndFullnodeAddressesEvent|UpdateNetworkAndFullnodeAddresses| |
|stake.move|IncreaseLockupEvent|IncreaseLockup| |
|stake.move|JoinValidatorSetEvent|JoinValidatorSet| |
|stake.move|DistributeRewardsEvent|DistributeRewards| |
|stake.move|UnlockStakeEvent|UnlockStake| |
|stake.move|WithdrawStakeEvent|WithdrawStake| |
|stake.move|LeaveValidatorSetEvent|LeaveValidatorSet| |
|staking_contract.move|UpdateCommissionEvent|UpdateCommission| |
|staking_contract.move|CreateStakingContractEvent|CreateStakingContract| |
|staking_contract.move|UpdateVoterEvent|UpdateVoter| |
|staking_contract.move|ResetLockupEvent|ResetLockup| |
|staking_contract.move|AddStakeEvent|AddStake| |
|staking_contract.move|RequestCommissionEvent|RequestCommission| |
|staking_contract.move|UnlockStakeEvent|UnlockStake| |
|staking_contract.move|SwitchOperatorEvent|SwitchOperator| |
|staking_contract.move|AddDistributionEvent|AddDistribution| |
|staking_contract.move|DistributeEvent|Distribute| |
|staking_contract.move|SwitchOperatorEvent|SwitchOperator| |
|vesting.move|CreateVestingContractEvent|CreateVestingContract| |
|vesting.move|UpdateOperatorEvent|UpdateOperator| |
|vesting.move|UpdateVoterEvent|UpdateVoter| |
|vesting.move|ResetLockupEvent|ResetLockup| |
|vesting.move|SetBeneficiaryEvent|SetBeneficiary| |
|vesting.move|UnlockRewardsEvent|UnlockRewards| |
|vesting.move|VestEvent|Vest| |
|vesting.move|DistributeEvent|Distribute| |
|vesting.move|TerminateEvent|Terminate| |
|vesting.move|AdminWithdrawEvent|AdminWithdraw| |
|voting.move|CreateProposalEvent|CreateProposal| |
|voting.move|RegisterForumEvent|RegisterForum| |
|voting.move|VoteEvent|Vote| |
|voting.move|ResolveProposal| | |
|token_event_store.move|CollectionDescriptionMutateEvent|CollectionDescriptionMutate| |
|token_event_store.move|CollectionUriMutateEvent|CollectionUriMutate| |
|token_event_store.move|CollectionMaxiumMutateEvent|CollectionMaxiumMutate| |
|token_event_store.move|OptInTransferEvent|OptInTransfer| |
|token_event_store.move|UriMutationEvent|UriMutation| |
|token_event_store.move|DefaultPropertyMutateEvent|DefaultPropertyMutate| |
|token_event_store.move|DescriptionMutateEvent|DescriptionMutate| |
|token_event_store.move|RoyaltyMutateEvent|RoyaltyMutate| |
|token_event_store.move|MaxiumMutateEvent|MaximumMutate| |

| Module | Event v1 Name | Event v2 Name | ABI update |
| :---------------------------------: | :------------------------------------: | :-------------------------------: | :------------------: |
| account.move | KeyRotationEvent | KeyRotation | +account:address |
| aptos_account.move | DirectCoinTransferConfigUpdatedEvent | DirectCoinTransferConfigUpdated | + account:address |
| coin.move | DepositEvent | Deposit | + account:address |
| coin.move | WithdrawEvent | Withdraw | + account: address |
| object.move | TransferEvent | Transfer | |
| aptos_governance.move | CreateProposalEvent | CreateProposal | |
| aptos_governance.move | VoteEvent | Vote | |
| aptos_governance.move | UpdateConfigEvent | UpdateConfig | |
| block.move | NewBlockEvent | NewBlock | |
| block.move | UpdateEpochIntervalEvent | UpdateEpochInterval | |
| aptos-token-objects/token.move | MutationEvent | Mutation | + token:address |
| aptos-token-objects/collection.move | MutationEvent | Mutation | + collection:address |
| aptos-token-objects/collection.move | BurnEvent | Burn | + previous_owner |
| aptos-token-objects/collection.move | MintEvent | Mint | + collection:address |
| multisig_account.move | AddOwnersEvent | AddOwners | + account: address |
| multisig_account.move | RemoveOwnersEvent | RemoveOwners | + account: address |
| multisig_account.move | UpdateSignaturesRequiredEvent | UpdateSignaturesRequired | + account: address |
| multisig_account.move | CreateTransactionEvent | CreateTransaction | + account: address |
| multisig_account.move | VoteEvent | Vote | + account: address |
| multisig_account.move | ExecuteRejectedTransactionEvent | ExecuteRejectedTransaction | + account: address |
| multisig_account.move | TransactionExecutionSucceededEvent | TransactionExecutionSucceeded | + account: address |
| multisig_account.move | TransactionExecutionFailedEvent | TransactionExecutionFailed | + account: address |
| multisig_account.move | MetadataUpdatedEvent | MetadataUpdated | + account: address |
| reconfiguration.move | NewEpochEvent | NewEpoch | |
| stake.move | RegisterValidatorCandidateEvent | RegisterValidatorCandidate | |
| stake.move | SetOperatorEvent | SetOperator | |
| stake.move | AddStakeEvent | AddStake | |
| stake.move | ReactivateStakeEvent | ReactivateStake | |
| stake.move | RotateConsensusKeyEvent | RotateConsensusKey | |
| stake.move | UpdateNetworkAndFullnodeAddressesEvent | UpdateNetworkAndFullnodeAddresses | |
| stake.move | IncreaseLockupEvent | IncreaseLockup | |
| stake.move | JoinValidatorSetEvent | JoinValidatorSet | |
| stake.move | DistributeRewardsEvent | DistributeRewards | |
| stake.move | UnlockStakeEvent | UnlockStake | |
| stake.move | WithdrawStakeEvent | WithdrawStake | |
| stake.move | LeaveValidatorSetEvent | LeaveValidatorSet | |
| staking_contract.move | UpdateCommissionEvent | UpdateCommission | |
| staking_contract.move | CreateStakingContractEvent | CreateStakingContract | |
| staking_contract.move | UpdateVoterEvent | UpdateVoter | |
| staking_contract.move | ResetLockupEvent | ResetLockup | |
| staking_contract.move | AddStakeEvent | AddStake | |
| staking_contract.move | RequestCommissionEvent | RequestCommission | |
| staking_contract.move | UnlockStakeEvent | UnlockStake | |
| staking_contract.move | SwitchOperatorEvent | SwitchOperator | |
| staking_contract.move | AddDistributionEvent | AddDistribution | |
| staking_contract.move | DistributeEvent | Distribute | |
| staking_contract.move | SwitchOperatorEvent | SwitchOperator | |
| vesting.move | CreateVestingContractEvent | CreateVestingContract | |
| vesting.move | UpdateOperatorEvent | UpdateOperator | |
| vesting.move | UpdateVoterEvent | UpdateVoter | |
| vesting.move | ResetLockupEvent | ResetLockup | |
| vesting.move | SetBeneficiaryEvent | SetBeneficiary | |
| vesting.move | UnlockRewardsEvent | UnlockRewards | |
| vesting.move | VestEvent | Vest | |
| vesting.move | DistributeEvent | Distribute | |
| vesting.move | TerminateEvent | Terminate | |
| vesting.move | AdminWithdrawEvent | AdminWithdraw | |
| voting.move | CreateProposalEvent | CreateProposal | |
| voting.move | RegisterForumEvent | RegisterForum | |
| voting.move | VoteEvent | Vote | |
| voting.move | ResolveProposal | | |
| token_event_store.move | CollectionDescriptionMutateEvent | CollectionDescriptionMutate | |
| token_event_store.move | CollectionUriMutateEvent | CollectionUriMutate | |
| token_event_store.move | CollectionMaxiumMutateEvent | CollectionMaxiumMutate | |
| token_event_store.move | OptInTransferEvent | OptInTransfer | |
| token_event_store.move | UriMutationEvent | UriMutation | |
| token_event_store.move | DefaultPropertyMutateEvent | DefaultPropertyMutate | |
| token_event_store.move | DescriptionMutateEvent | DescriptionMutate | |
| token_event_store.move | RoyaltyMutateEvent | RoyaltyMutate | |
| token_event_store.move | MaxiumMutateEvent | MaximumMutate | |


### Event V2 Translation Engine

Aptos Labs will support the event v2 translation engine to facilitate the migration process. Aptos Labs will provide the temporary REST API path `https://api.mainnet.aptoslabs.com/translated/v1`. Even after the event migration is enabled, the REST Node API will still be able to query the event v1. The supported APIs are as follows:
- Events by creation number: `GET /accounts/{address}/events/{creation_number}`
- Events by handle: `GET /accounts/{address}/events/{event_handle}/{field_name}`
- Transactions: `GET /transactions`
- Transactions by version: `GET /transactions/by_version/{txn_version}`
- Transactions by hash: `GET /transactions/by_hash/{txn_hash}`
- Account transactions: `GET /accounts/{address}/transactions`
- Transaction simulation: `POST /transactions/simulate`

The event v2 translation engine will support translation for the account, coin and token related events, which are listed below:
- CoinDeposit
- CoinWithdraw
- CoinRegister
- KeyRotation
- Transfer
- TokenMutation
- CollectionMutation
- Mint
- Burn
- TokenDeposit
- TokenWithdraw
- BurnToken
- MutatePropertyMap
- MintToken
- CreateCollection
- TokenDataCreation
- Offer
- CancelOffer
- Claim
- CollectionDescriptionMutate
- CollectionUriMutate
- CollectionMaximumMutate
- UriMutation
- DefaultPropertyMutate
- DescriptionMutate
- RoyaltyMutate
- MaximumMutate
- OptInTransfer

## Reference Implementation

https://github.com/aptos-labs/aptos-core/pull/10532

https://github.com/aptos-labs/aptos-core/pull/11688

Event v2 translation: https://github.com/aptos-labs/aptos-core/pull/14615

## Risks and Drawbacks

During the migration,
Expand Down